lambder 3.7.1 → 4.0.1

package/dist/testing.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Testing entry point (`import ... from "lambder/testing"`).
+ *
+ * Mock tooling that neither the server nor the production client bundle
+ * should carry: the MSW adapter that serves an app's typed API contract
+ * from in-browser mock handlers during development and tests.
+ */
+export { default as LambderMSW } from "./client/LambderMSW.js";
+export type { LambderMswModule } from "./client/LambderMSW.js";

package/dist/testing.js

@@ -0,0 +1,8 @@
+/**
+ * Testing entry point (`import ... from "lambder/testing"`).
+ *
+ * Mock tooling that neither the server nor the production client bundle
+ * should carry: the MSW adapter that serves an app's typed API contract
+ * from in-browser mock handlers during development and tests.
+ */
+export { default as LambderMSW } from "./client/LambderMSW.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lambder",
-  "version": "3.7.1",
+  "version": "4.0.1",
   "description": "",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -9,6 +9,24 @@
     ".": {
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
+    },
+    "./client": {
+      "types": "./dist/client.d.ts",
+      "default": "./dist/client.js"
+    },
+    "./testing": {
+      "types": "./dist/testing.d.ts",
+      "default": "./dist/testing.js"
+    }
+  },
+  "typesVersions": {
+    "*": {
+      "client": [
+        "./dist/client.d.ts"
+      ],
+      "testing": [
+        "./dist/testing.d.ts"
+      ]
     }
   },
   "browser": {

package/dist/LambderApiContract.d.ts

@@ -1,21 +0,0 @@
-/**
- * Lambder API Contract System
- *
- * Contracts are built via method chaining and inferred using typeof lambder.ApiContract
- */
-/**
- * Base shape for API contracts - used by LambderCaller and LambderMSW
- */
-export type ApiContractShape = Record<string, {
-    input: any;
-    output: any;
-}>;
-/**
- * Helper type for merging new API into existing contract during chaining
- */
-export type MergeContract<Old, Name extends string, In, Out> = Old & {
-    [K in Name]: {
-        input: In;
-        output: Out;
-    };
-};

package/dist/LambderApiPolicies.d.ts

@@ -1,177 +0,0 @@
-import type { z } from "zod";
-import type { LambderRenderContext } from "./LambderContext.js";
-import type LambderResolver from "./LambderResolver.js";
-import type { LambderRateLimitPolicy, LambderDdbRateLimiter } from "./LambderDdbRateLimiter.js";
-import type { LambderDdbIdempotency } from "./LambderDdbIdempotency.js";
-import { LambderResponse } from "./LambderResponse.js";
-/**
- * A custom rate-limit key: `input` names the payload fields the key needs.
- * The slice is validated against the raw payload before `handler` runs (a
- * failure answers the standard 422 validation shape), and the requirement is
- * merged into the contract input of every API that references the policy, so
- * clients are forced by the compiler to send those fields. Build with
- * lambderRateLimitKey() so the handler's payload type follows `input`.
- */
-export type LambderRateLimitKeyFn<TInput extends z.ZodTypeAny = z.ZodTypeAny> = {
-    input: TInput;
-    handler: (ctx: LambderRenderContext, payload: z.output<TInput>) => string | Promise<string>;
-} | {
-    input?: undefined;
-    handler: (ctx: LambderRenderContext, payload: undefined) => string | Promise<string>;
-};
-/**
- * Builder that ties the handler's payload type to the `input` schema inside
- * one literal. Returns the exact union member (not the union), so requirement
- * extraction can see the `input` type.
- */
-export declare function lambderRateLimitKey<TInput extends z.ZodTypeAny>(key: {
-    input: TInput;
-    handler: (ctx: LambderRenderContext, payload: z.output<TInput>) => string | Promise<string>;
-}): {
-    input: TInput;
-    handler: (ctx: LambderRenderContext, payload: z.output<TInput>) => string | Promise<string>;
-};
-export declare function lambderRateLimitKey(key: {
-    handler: (ctx: LambderRenderContext, payload: undefined) => string | Promise<string>;
-}): {
-    input?: undefined;
-    handler: (ctx: LambderRenderContext, payload: undefined) => string | Promise<string>;
-};
-/** What one rate-limit counter tracks: the client IP, the session identity, or a custom payload-derived key. */
-export type LambderRateLimitPer = "ip" | "session" | LambderRateLimitKeyFn<any>;
-/** A named rate-limit policy: fixed windows plus the key one counter tracks. */
-export type LambderApiRateLimitPolicyConfig = LambderRateLimitPolicy & {
-    per: LambderRateLimitPer;
-    /** Envelope errorMessage for refused requests. Default: a generic too-many-requests message. */
-    errorMessage?: any;
-};
-export type LambderApiRateLimitsConfig<TPolicies extends Record<string, LambderApiRateLimitPolicyConfig>> = {
-    /** Your limiter instance; its table, keyPrefix and failOpen apply as configured on it. */
-    limiter: LambderDdbRateLimiter;
-    /** Named policies referenced (typed) from addApi/addSessionApi. */
-    policies: TPolicies;
-};
-export type LambderApiIdempotencyConfig = {
-    /** Your idempotency store instance; may share the rate limiter's table (distinct key prefix). */
-    store: LambderDdbIdempotency;
-    /** Seconds a stored response replays for. Default: 86400 (24h). Per-API override: idempotency: { ttlSeconds }. */
-    defaultTtlSeconds?: number;
-    /** Skip idempotency (execute normally) when DynamoDB errors, instead of failing the request. Default: true. */
-    failOpen?: boolean;
-};
-/**
- * A named guard, run before the API's own input validation. `input` names the
- * payload fields the guard requires: the slice is validated against the raw
- * payload before `handler` runs (a failure answers the standard 422
- * validation shape), the handler receives it typed, and the requirement is
- * merged into the contract input of every API that declares the guard, so
- * clients are forced by the compiler to send those fields. The handler
- * refuses by throwing (typically refuse()/LambderApiError). Build with
- * lambderGuard() so the handler's payload type follows `input`.
- */
-export type LambderApiGuard<TInput extends z.ZodTypeAny = z.ZodTypeAny> = {
-    input: TInput;
-    handler: (ctx: LambderRenderContext, payload: z.output<TInput>, res: LambderResolver) => void | Promise<void>;
-} | {
-    input?: undefined;
-    handler: (ctx: LambderRenderContext, payload: undefined, res: LambderResolver) => void | Promise<void>;
-};
-/**
- * Builder that ties the handler's payload type to the `input` schema inside
- * one literal. Returns the exact union member (not the union), so requirement
- * extraction can see the `input` type.
- */
-export declare function lambderGuard<TInput extends z.ZodTypeAny>(guard: {
-    input: TInput;
-    handler: (ctx: LambderRenderContext, payload: z.output<TInput>, res: LambderResolver) => void | Promise<void>;
-}): {
-    input: TInput;
-    handler: (ctx: LambderRenderContext, payload: z.output<TInput>, res: LambderResolver) => void | Promise<void>;
-};
-export declare function lambderGuard(guard: {
-    handler: (ctx: LambderRenderContext, payload: undefined, res: LambderResolver) => void | Promise<void>;
-}): {
-    input?: undefined;
-    handler: (ctx: LambderRenderContext, payload: undefined, res: LambderResolver) => void | Promise<void>;
-};
-/** Names of policies usable on public APIs: everything not keyed per "session". */
-export type LambderPublicRateLimitNames<TPolicies> = {
-    [K in keyof TPolicies]: TPolicies[K] extends {
-        per: "session";
-    } ? never : K;
-}[keyof TPolicies] & string;
-/** Payload fields a guard requires; {} when it declares no input. */
-export type LambderGuardPayload<G> = G extends {
-    input: infer S extends z.ZodTypeAny;
-} ? z.output<S> : {};
-/** Guard name to required-payload map, accumulated on the Lambder instance by defineApiGuards. */
-export type LambderGuardPayloadMap<TGuards> = {
-    [K in keyof TGuards]: LambderGuardPayload<TGuards[K]>;
-};
-/** Payload fields a policy's custom key requires; {} for "ip"/"session" or keys with no input. */
-export type LambderPolicyPayload<P> = P extends {
-    per: {
-        input: infer S extends z.ZodTypeAny;
-    };
-} ? z.output<S> : {};
-type UnionToIntersection<U> = (U extends any ? (x: U) => void : never) extends (x: infer I) => void ? I : never;
-type NamesIn<TOpt> = TOpt extends readonly (infer N extends string)[] ? N : TOpt extends string ? TOpt : never;
-/** Intersection of the payload requirements of the referenced guards; never when none are declared. */
-export type LambderGuardsRequirement<TGuardPayloads, TOpt> = [
-    NamesIn<TOpt>
-] extends [never] ? never : UnionToIntersection<TGuardPayloads[Extract<NamesIn<TOpt>, keyof TGuardPayloads>]>;
-/** Intersection of the payload requirements of the referenced rate-limit policies; never when none are declared. */
-export type LambderPoliciesRequirement<TPolicies, TOpt> = [
-    NamesIn<TOpt>
-] extends [never] ? never : UnionToIntersection<LambderPolicyPayload<TPolicies[Extract<NamesIn<TOpt>, keyof TPolicies>]>>;
-/** Contract-input merge: the API's own input plus everything its rate limits and guards force clients to send. */
-export type LambderMergedInput<TIn, TReqA, TReqB> = ([TReqA] extends [never] ? TIn : TIn & TReqA) extends infer TMid ? ([TReqB] extends [never] ? TMid : TMid & TReqB) : never;
-/**
- * Runtime side of the declarative API options: holds what the enable/define
- * calls declared, asserts registrations against it at startup, and executes
- * rate limits, guards, and idempotency around handlers at request time.
- * Internal to Lambder; apps interact through enableApiRateLimits(),
- * enableApiIdempotency(), defineApiGuards() and the per-API options.
- */
-export declare class LambderApiPolicyEngine {
-    private limiter;
-    private rateLimitPolicies;
-    private guards;
-    private idempotencyStore;
-    private idempotencyDefaultTtlSeconds;
-    private idempotencyFailOpen;
-    setRateLimits(config: LambderApiRateLimitsConfig<Record<string, LambderApiRateLimitPolicyConfig>>): void;
-    addGuards(guards: Record<string, LambderApiGuard<any>>): void;
-    setIdempotency(config: LambderApiIdempotencyConfig): void;
-    /** Startup validation of one API registration's declarative options. */
-    assertRegistration(apiName: string, mode: "public" | "session", options: {
-        rateLimit?: string | readonly string[];
-        guards?: string | readonly string[];
-        idempotency?: unknown;
-    }): void;
-    /** Rate limits then guards, in declared order. Refusals throw (LambderApiError or a guard's own throw). */
-    runPreflight(apiName: string, ctx: LambderRenderContext, resolver: LambderResolver, options: {
-        rateLimit?: string | readonly string[];
-        guards?: string | readonly string[];
-    }): Promise<void>;
-    /**
-     * Validate a preflight input slice against the raw payload. Runs before
-     * the API's own validation, so guard/key requirements hold even when the
-     * API schema does not declare (and would strip) those fields. Failures
-     * answer the same 422 shape as regular input validation.
-     */
-    private parseSlice;
-    private resolveRateLimitKey;
-    /**
-     * Idempotency wrapper around validation-passed handler execution. Without
-     * a client idempotencyKey the handler just runs; with one, the scope
-     * (identity + api + key) is claimed atomically: duplicates of an
-     * in-flight original refuse with 409, replays of a completed one return
-     * the stored response verbatim, and a crashed original releases its claim
-     * so a retry actually retries.
-     */
-    withIdempotency(apiName: string, ctx: LambderRenderContext, config: boolean | {
-        ttlSeconds?: number;
-    }, exec: () => Promise<LambderResponse>): Promise<LambderResponse>;
-}
-export {};

package/dist/LambderApiPolicies.js

@@ -1,219 +0,0 @@
-import { LambderApiError } from "./LambderApiError.js";
-import { LambderResponse } from "./LambderResponse.js";
-/** A crashed original must not block retries forever: pending claims expire on their own. */
-const IDEMPOTENCY_PENDING_TTL_SECONDS = 300;
-/** Responses above this size skip replay storage (DynamoDB item limit is 400KB). */
-const IDEMPOTENCY_MAX_STORED_BODY_BYTES = 350_000;
-const RATE_LIMIT_WINDOW_KEYS = ["perMin", "per10Min", "perHour", "perDay", "perWeek", "perMonth"];
-export function lambderRateLimitKey(key) { return key; }
-export function lambderGuard(guard) { return guard; }
-const toList = (value) => value === undefined ? [] : typeof value === "string" ? [value] : value;
-/**
- * Runtime side of the declarative API options: holds what the enable/define
- * calls declared, asserts registrations against it at startup, and executes
- * rate limits, guards, and idempotency around handlers at request time.
- * Internal to Lambder; apps interact through enableApiRateLimits(),
- * enableApiIdempotency(), defineApiGuards() and the per-API options.
- */
-export class LambderApiPolicyEngine {
-    limiter = null;
-    rateLimitPolicies = {};
-    guards = {};
-    idempotencyStore = null;
-    idempotencyDefaultTtlSeconds = 24 * 3600;
-    idempotencyFailOpen = true;
-    setRateLimits(config) {
-        if (this.limiter)
-            throw new Error("Lambder: enableApiRateLimits() was already called.");
-        for (const [name, policy] of Object.entries(config.policies)) {
-            const per = policy.per;
-            if (!per || (per !== "ip" && per !== "session" && typeof per.handler !== "function")) {
-                throw new Error(`Lambder: rate-limit policy "${name}" needs per: "ip", "session", or a { input?, handler } key.`);
-            }
-            if (!RATE_LIMIT_WINDOW_KEYS.some((key) => policy[key])) {
-                throw new Error(`Lambder: rate-limit policy "${name}" declares no window (${RATE_LIMIT_WINDOW_KEYS.join("/")}).`);
-            }
-        }
-        this.limiter = config.limiter;
-        this.rateLimitPolicies = { ...config.policies };
-    }
-    addGuards(guards) {
-        for (const [name, guardDef] of Object.entries(guards)) {
-            if (this.guards[name])
-                throw new Error(`Lambder: guard "${name}" is already defined.`);
-            if (typeof guardDef?.handler !== "function")
-                throw new Error(`Lambder: guard "${name}" has no handler function.`);
-            this.guards[name] = guardDef;
-        }
-    }
-    setIdempotency(config) {
-        if (this.idempotencyStore)
-            throw new Error("Lambder: enableApiIdempotency() was already called.");
-        this.idempotencyStore = config.store;
-        this.idempotencyDefaultTtlSeconds = config.defaultTtlSeconds ?? 24 * 3600;
-        this.idempotencyFailOpen = config.failOpen ?? true;
-    }
-    /** Startup validation of one API registration's declarative options. */
-    assertRegistration(apiName, mode, options) {
-        for (const name of toList(options.rateLimit)) {
-            const policy = this.rateLimitPolicies[name];
-            if (!policy) {
-                throw new Error(`Lambder: API "${apiName}" references unknown rate-limit policy "${name}". Declare it via enableApiRateLimits() before registering the API.`);
-            }
-            if (policy.per === "session" && mode !== "session") {
-                throw new Error(`Lambder: API "${apiName}" uses rate-limit policy "${name}" (per "session"), which requires addSessionApi.`);
-            }
-        }
-        for (const name of toList(options.guards)) {
-            if (!this.guards[name]) {
-                throw new Error(`Lambder: API "${apiName}" references unknown guard "${name}". Define it via defineApiGuards() before registering the API.`);
-            }
-        }
-        if (options.idempotency !== undefined && !this.idempotencyStore) {
-            throw new Error(`Lambder: API "${apiName}" declares idempotency but enableApiIdempotency() was not called first.`);
-        }
-    }
-    /** Rate limits then guards, in declared order. Refusals throw (LambderApiError or a guard's own throw). */
-    async runPreflight(apiName, ctx, resolver, options) {
-        for (const name of toList(options.rateLimit)) {
-            const policy = this.rateLimitPolicies[name];
-            if (!policy || !this.limiter)
-                throw new Error(`Lambder: rate-limit policy "${name}" is not configured.`);
-            const key = await this.resolveRateLimitKey(ctx, resolver, policy.per);
-            const limited = await this.limiter.isRateLimited(`api|${apiName}|${name}|${key}`, policy);
-            if (limited) {
-                throw new LambderApiError(`Rate limited: "${apiName}" exceeded policy "${name}".`, {
-                    errorMessage: policy.errorMessage ?? "Too many requests. Please try again later.",
-                    statusCode: 429,
-                });
-            }
-        }
-        for (const name of toList(options.guards)) {
-            const guardDef = this.guards[name];
-            if (!guardDef)
-                throw new Error(`Lambder: guard "${name}" is not configured.`);
-            const payload = this.parseSlice(guardDef.input, ctx, resolver);
-            await guardDef.handler(ctx, payload, resolver);
-        }
-    }
-    /**
-     * Validate a preflight input slice against the raw payload. Runs before
-     * the API's own validation, so guard/key requirements hold even when the
-     * API schema does not declare (and would strip) those fields. Failures
-     * answer the same 422 shape as regular input validation.
-     */
-    parseSlice(input, ctx, resolver) {
-        if (!input)
-            return undefined;
-        const parsed = input.safeParse(ctx.post?.payload);
-        if (!parsed.success) {
-            throw resolver.json({ error: "Input validation failed", zodError: parsed.error }, { statusCode: 422 });
-        }
-        return parsed.data;
-    }
-    async resolveRateLimitKey(ctx, resolver, per) {
-        if (per === "ip")
-            return `ip:${ctx.ip}`;
-        if (per === "session") {
-            const sessionKey = ctx.session?.sessionKey;
-            if (!sessionKey)
-                throw new Error('Lambder: rate-limit per "session" evaluated without a session on the context.');
-            return `session:${sessionKey}`;
-        }
-        const payload = this.parseSlice(per.input, ctx, resolver);
-        return `custom:${await per.handler(ctx, payload)}`;
-    }
-    /**
-     * Idempotency wrapper around validation-passed handler execution. Without
-     * a client idempotencyKey the handler just runs; with one, the scope
-     * (identity + api + key) is claimed atomically: duplicates of an
-     * in-flight original refuse with 409, replays of a completed one return
-     * the stored response verbatim, and a crashed original releases its claim
-     * so a retry actually retries.
-     */
-    async withIdempotency(apiName, ctx, config, exec) {
-        const store = this.idempotencyStore;
-        const rawKey = ctx.post?.idempotencyKey;
-        if (!store || rawKey === undefined || rawKey === null)
-            return await exec();
-        if (typeof rawKey !== "string" || rawKey.length < 1 || rawKey.length > 200) {
-            throw new LambderApiError("Invalid idempotency key.", { statusCode: 400 });
-        }
-        const ttlSeconds = (typeof config === "object" ? config.ttlSeconds : undefined) ?? this.idempotencyDefaultTtlSeconds;
-        // Scoped per identity so clients cannot collide with or poison each other's keys.
-        const sessionKey = ctx.session?.sessionKey;
-        const scopeKey = `${sessionKey ? `s:${sessionKey}` : `ip:${ctx.ip}`}|${apiName}|${rawKey}`;
-        let begun;
-        try {
-            begun = await store.begin(scopeKey, { pendingTtlSeconds: IDEMPOTENCY_PENDING_TTL_SECONDS });
-        }
-        catch (err) {
-            if (this.idempotencyFailOpen)
-                return await exec();
-            throw err;
-        }
-        if (begun.state === "pending") {
-            throw new LambderApiError(`Duplicate request for "${apiName}": the original is still processing.`, {
-                statusCode: 409,
-                errorMessage: "This request is already being processed.",
-            });
-        }
-        if (begun.state === "done") {
-            return new LambderResponse({
-                statusCode: begun.statusCode,
-                headers: begun.contentType ? { "Content-Type": begun.contentType } : {},
-                body: begun.body,
-            });
-        }
-        const ownerToken = begun.ownerToken;
-        // Store the response for replays when it qualifies, release the claim
-        // otherwise. Settle failures only surface when failing closed.
-        const settleClaim = async (response) => {
-            const cacheable = response.statusCode < 500
-                && typeof response.body === "string"
-                && !response.isBodyBase64
-                && response.body.length <= IDEMPOTENCY_MAX_STORED_BODY_BYTES;
-            try {
-                if (cacheable) {
-                    await store.complete(scopeKey, ownerToken, {
-                        statusCode: response.statusCode,
-                        contentType: response.getHeader("Content-Type")?.[0] ?? null,
-                        body: response.body,
-                        ttlSeconds,
-                    });
-                }
-                else {
-                    await store.abandon(scopeKey, ownerToken);
-                }
-            }
-            catch (storeErr) {
-                if (!this.idempotencyFailOpen)
-                    throw storeErr;
-            }
-        };
-        try {
-            const response = await exec();
-            await settleClaim(response);
-            return response;
-        }
-        catch (err) {
-            // A thrown LambderResponse IS the response (res.die.*, throw
-            // res.api(...)): settle the claim like a returned one so its side
-            // effect replays, then rethrow so the pipeline emits it.
-            if (err instanceof LambderResponse) {
-                await settleClaim(err);
-                throw err;
-            }
-            // A real crash (or a refusal like LambderApiError) releases the
-            // claim so a retry actually retries.
-            try {
-                await store.abandon(scopeKey, ownerToken);
-            }
-            catch (cleanupErr) {
-                if (!this.idempotencyFailOpen)
-                    throw cleanupErr;
-            }
-            throw err;
-        }
-    }
-}