lambder 6.0.1 → 7.0.1

package/dist/shared/{LambderApiError.d.ts → wire/LambderApiRefusal.d.ts}

@@ -1,13 +1,13 @@
-import type { HttpStatusCode } from "../core/LambderResponse.js";
-export type LambderApiErrorOptions = {
+import type { LambderHttpStatusCode } from "./LambderHttpStatus.js";
+export type LambderApiRefusalOptions = {
     /**
-     * Structured, user-facing failure detail placed on the API envelope's
-     * `errorMessage` field. Any shape the app's errorMessageHandler expects
-     * (e.g. `{ type: "warning", content: "..." }`). Defaults to the error
-     * message string, so a bare `throw new LambderApiError("...")` is still
+     * User-facing failure detail placed on the API envelope's `errorMessage`
+     * field: a refusal message (`{ type: "warning", content: "..." }`, with
+     * an app's own `code`) or a plain string. Defaults to the error message
+     * string, so a bare `throw new LambderApiRefusal("...")` is still
      * visible to the client.
      */
-    errorMessage?: any;
+    errorMessage?: LambderAppRefusalMessage | string;
     /** Sets the envelope's `notAuthorized` flag (routed to the caller's notAuthorizedHandler). */
     notAuthorized?: boolean;
     /** Sets the envelope's `sessionExpired` flag (the caller clears session cookies and calls sessionExpiredHandler). */
@@ -17,7 +17,7 @@ export type LambderApiErrorOptions = {
      * semantic channel. Avoid 5xx (LambderCaller treats those as crashes) and
      * 422 (reserved for input validation).
      */
-    statusCode?: HttpStatusCode;
+    statusCode?: LambderHttpStatusCode;
     /** Extra response headers on the refusal (e.g. Retry-After on a rate limit). */
     headers?: Record<string, string>;
     /** Underlying cause, preserved on the standard Error `cause` property. */
@@ -25,8 +25,8 @@ export type LambderApiErrorOptions = {
 };
 /**
  * A typed refusal: "this request is denied/invalid" as opposed to "the server
- * crashed". Throw it from anywhere in an API call's call stack — handlers,
- * hooks, or nested helpers that have no access to the per-request resolver —
+ * crashed". Throw it from anywhere in an API call's call stack (handlers,
+ * hooks, or nested helpers that have no access to the per-request resolver)
  * and the render pipeline maps it onto the structured API envelope
  * (`res.api(null, { errorMessage, notAuthorized, sessionExpired })`) instead
  * of routing it through setGlobalErrorHandler. Refusals therefore never reach
@@ -39,22 +39,22 @@ export type LambderApiErrorOptions = {
  * checks) may import and throw it from packages used by both server and
  * browser builds; in the browser it is just an Error.
  */
-export declare class LambderApiError extends Error {
+export declare class LambderApiRefusal extends Error {
     /**
      * Brand for detection across duplicate lambder installs: when two copies
-     * of the package coexist in one bundle, `instanceof LambderApiError` fails
+     * of the package coexist in one bundle, `instanceof LambderApiRefusal` fails
      * across them while this marker does not. The pipeline checks the brand.
      */
-    readonly isLambderApiError = true;
-    readonly errorMessage?: any;
+    readonly isLambderApiRefusal = true;
+    readonly errorMessage?: LambderAppRefusalMessage | string;
     readonly notAuthorized?: boolean;
     readonly sessionExpired?: boolean;
-    readonly statusCode?: HttpStatusCode;
+    readonly statusCode?: LambderHttpStatusCode;
     readonly headers?: Record<string, string>;
-    constructor(message: string, options?: LambderApiErrorOptions);
+    constructor(message: string, options?: LambderApiRefusalOptions);
 }
-/** Brand-based type guard (see LambderApiError.isLambderApiError). */
-export declare const isLambderApiError: (err: unknown) => err is LambderApiError;
+/** Brand-based type guard (see LambderApiRefusal.isLambderApiRefusal). */
+export declare const isLambderApiRefusal: (err: unknown) => err is LambderApiRefusal;
 /**
  * The standard shape refusals carry on the envelope's errorMessage field.
  * `code` is the refusal's machine-readable identity: clients branch and
@@ -62,16 +62,36 @@ export declare const isLambderApiError: (err: unknown) => err is LambderApiError
  * human-readable fallback for codes a client does not know yet. Apps keep
  * their own typed code vocabulary; the framework's own refusals carry a
  * LambderRefusalCode. The caller's errorMessageHandler receives the object
- * as-is; apps with their own errorMessage vocabulary can keep using
- * LambderApiError directly instead.
+ * as-is, typed as LambderAppRefusalMessage or a plain string; an app's own
+ * vocabulary goes in `code`.
  */
-export type LambderRefusalMessage = {
+export type LambderRefusalMessage<TAppCode extends string = never> = {
     type: "warning" | "error" | "info";
-    /** Machine-readable identity of the refusal (the app's own vocabulary, or a LambderRefusalCode). */
-    code?: string;
+    /**
+     * Machine-readable identity of the refusal: a LambderRefusalCode, plus
+     * whatever vocabulary the reader names in TAppCode.
+     *
+     * Parameterized rather than widened with `string & {}`, because a union
+     * with `string` in it does not narrow: inside a `switch(message.code)`
+     * the case was not assignable and the `default: never` assertion failed,
+     * which is exactly the exhaustiveness the codes exist for. A client that
+     * reads its own vocabulary declares it
+     * (`LambderRefusalMessage<"app/not-verified" | ...>`) and gets a switch
+     * that is checked; a value an app WRITES takes LambderAppRefusalMessage,
+     * where any code is welcome.
+     */
+    code?: LambderRefusalCode | TAppCode;
     title?: string;
     content: string;
 };
+/**
+ * The refusal shape an app authors: any code, with the framework's own still
+ * autocompleting. What every option that takes a message from an app is
+ * typed as (a rate-limit policy's errorMessage, the mock's failure
+ * injection); LambderRefusalMessage itself defaults to the framework's codes
+ * alone, so a reader's switch over it is exhaustive.
+ */
+export type LambderAppRefusalMessage = LambderRefusalMessage<string & {}>;
 /**
  * Codes the framework stamps on the refusals it authors itself, under the
  * reserved `lambder/` prefix so app codes never collide. Compare against
@@ -89,6 +109,8 @@ export declare const LAMBDER_REFUSAL_CODES: {
     readonly apiNotFound: "lambder/api-not-found";
     /** The request's compressed payload is malformed or over the size limit (400). */
     readonly invalidRequestPayload: "lambder/invalid-request-payload";
+    /** Only the mock runtime emits it: the endpoint is registered as not mocked, with a reason. */
+    readonly notMocked: "lambder/not-mocked";
 };
 export type LambderRefusalCode = (typeof LAMBDER_REFUSAL_CODES)[keyof typeof LAMBDER_REFUSAL_CODES];
 export type LambderRefuseOptions = {
@@ -103,7 +125,7 @@ export type LambderRefuseOptions = {
     /** Sets the envelope's sessionExpired flag. */
     sessionExpired?: boolean;
     /** HTTP status of the refusal. Default 200; avoid 5xx (caller treats as crash) and 422 (reserved for validation). */
-    statusCode?: HttpStatusCode;
+    statusCode?: LambderHttpStatusCode;
     /** Extra response headers on the refusal (e.g. Retry-After). */
     headers?: Record<string, string>;
     /** Underlying cause, preserved on the Error cause property. */
@@ -111,10 +133,10 @@ export type LambderRefuseOptions = {
 };
 /**
  * Refuse the current API call: a routine business "no" (not found, invalid
- * input, not allowed) with a user-facing message. Throws a LambderApiError
+ * input, not allowed) with a user-facing message. Throws a LambderApiRefusal
  * carrying the standard LambderRefusalMessage shape, so the pipeline maps it
  * onto the structured envelope instead of a 500, and crash logging never
- * sees it. Callable from anywhere in the call stack — handlers, hooks,
+ * sees it. Callable from anywhere in the call stack: handlers, hooks,
  * guards, shared helpers with no resolver access.
  *
  * The const carries the annotation so TypeScript applies never-return

package/dist/shared/{LambderApiError.js → wire/LambderApiRefusal.js}

@@ -1,7 +1,7 @@
 /**
  * A typed refusal: "this request is denied/invalid" as opposed to "the server
- * crashed". Throw it from anywhere in an API call's call stack — handlers,
- * hooks, or nested helpers that have no access to the per-request resolver —
+ * crashed". Throw it from anywhere in an API call's call stack (handlers,
+ * hooks, or nested helpers that have no access to the per-request resolver)
  * and the render pipeline maps it onto the structured API envelope
  * (`res.api(null, { errorMessage, notAuthorized, sessionExpired })`) instead
  * of routing it through setGlobalErrorHandler. Refusals therefore never reach
@@ -14,13 +14,13 @@
  * checks) may import and throw it from packages used by both server and
  * browser builds; in the browser it is just an Error.
  */
-export class LambderApiError extends Error {
+export class LambderApiRefusal extends Error {
     /**
      * Brand for detection across duplicate lambder installs: when two copies
-     * of the package coexist in one bundle, `instanceof LambderApiError` fails
+     * of the package coexist in one bundle, `instanceof LambderApiRefusal` fails
      * across them while this marker does not. The pipeline checks the brand.
      */
-    isLambderApiError = true;
+    isLambderApiRefusal = true;
     errorMessage;
     notAuthorized;
     sessionExpired;
@@ -28,7 +28,7 @@ export class LambderApiError extends Error {
     headers;
     constructor(message, options = {}) {
         super(message, options.cause !== undefined ? { cause: options.cause } : undefined);
-        this.name = "LambderApiError";
+        this.name = "LambderApiRefusal";
         this.errorMessage = options.errorMessage ?? message;
         this.notAuthorized = options.notAuthorized;
         this.sessionExpired = options.sessionExpired;
@@ -36,8 +36,8 @@ export class LambderApiError extends Error {
         this.headers = options.headers;
     }
 }
-/** Brand-based type guard (see LambderApiError.isLambderApiError). */
-export const isLambderApiError = (err) => err instanceof Error && err.isLambderApiError === true;
+/** Brand-based type guard (see LambderApiRefusal.isLambderApiRefusal). */
+export const isLambderApiRefusal = (err) => err instanceof Error && err.isLambderApiRefusal === true;
 /**
  * Codes the framework stamps on the refusals it authors itself, under the
  * reserved `lambder/` prefix so app codes never collide. Compare against
@@ -55,13 +55,15 @@ export const LAMBDER_REFUSAL_CODES = {
     apiNotFound: "lambder/api-not-found",
     /** The request's compressed payload is malformed or over the size limit (400). */
     invalidRequestPayload: "lambder/invalid-request-payload",
+    /** Only the mock runtime emits it: the endpoint is registered as not mocked, with a reason. */
+    notMocked: "lambder/not-mocked",
 };
 /**
  * Refuse the current API call: a routine business "no" (not found, invalid
- * input, not allowed) with a user-facing message. Throws a LambderApiError
+ * input, not allowed) with a user-facing message. Throws a LambderApiRefusal
  * carrying the standard LambderRefusalMessage shape, so the pipeline maps it
  * onto the structured envelope instead of a 500, and crash logging never
- * sees it. Callable from anywhere in the call stack — handlers, hooks,
+ * sees it. Callable from anywhere in the call stack: handlers, hooks,
  * guards, shared helpers with no resolver access.
  *
  * The const carries the annotation so TypeScript applies never-return
@@ -69,7 +71,7 @@ export const LAMBDER_REFUSAL_CODES = {
  * `row` is defined afterwards).
  */
 export const refuse = (content, options = {}) => {
-    throw new LambderApiError(content, {
+    throw new LambderApiRefusal(content, {
         errorMessage: {
             type: options.type ?? "warning",
             ...(options.code !== undefined ? { code: options.code } : {}),

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

@@ -0,0 +1,171 @@
+/**
+ * The per-call options both callers take, the contract-driven typing of a
+ * call's arguments, and the runtime merge of guard inputs, shared by the
+ * browser caller (LambderCaller) and the server-side invoke caller
+ * (LambderInvokeCaller). Both speak the same envelope to the same kind of
+ * contract, so what an API demands of its caller (a guardInput-mode guard's
+ * value, say) is decided here once and the two callers cannot drift on it.
+ * Pure types and one dependency-free function, so the browser entry resolves
+ * it.
+ */
+import type { LambderContractIdempotencyOf } from "./LambderApiContract.js";
+type IsAny<T> = 0 extends (1 & T) ? true : false;
+/**
+ * The options every call takes, whichever caller sends it. Each caller adds
+ * its own on top: the browser's per-call handler overrides, the invoke
+ * caller's `clientIp` and `session`.
+ */
+export type LambderSharedCallOptions = {
+    /** Extra request headers the server sees. */
+    headers?: Record<string, string>;
+    /** Abort the call after this many ms; overrides the constructor default. */
+    timeoutMs?: number;
+    /** External abort signal, combined with the timeout when both are set. */
+    signal?: AbortSignal;
+    /**
+     * Overrides the constructor's requestCompression for this call: `false`
+     * sends the payload plainly (a hot path where the CPU matters more than
+     * the bytes), `true` compresses it regardless of the size threshold.
+     * Either way a payload is only sent compressed when that is smaller.
+     */
+    compressRequest?: boolean;
+    /**
+     * Values for the API's guardInput-mode guards, keyed by guard name; sent
+     * beside the payload and consumed by the guards before validation. The
+     * typed contract makes this REQUIRED for APIs that declare such guards,
+     * except the guards a guardInputsProvider covers (these merge on top of
+     * the provider's values).
+     */
+    guardInputs?: Record<string, unknown>;
+    /**
+     * Replay-protection key for APIs declared idempotent on the server.
+     * Generate once per logical operation with
+     * LambderCaller.createIdempotencyKey() and send the same key on retries:
+     * duplicates of an in-flight request refuse, and repeats of a completed
+     * one replay its stored response instead of re-executing. Must be
+     * UNGUESSABLE random (it scopes the replay record for logged-out clients)
+     * and at least 16 characters; the server refuses shorter keys with a 400.
+     *
+     * The typed contract makes this REQUIRED for an API whose entry declares
+     * `idempotency`, the way it does for guardInput values: a server
+     * declaration that reads as protection and silently provides none (the
+     * server runs a keyless call, which dedupes nothing) is exactly what the
+     * typed caller is for.
+     */
+    idempotencyKey?: string;
+};
+/** The payload type one API of a contract takes; `any` for an untyped caller or a name the contract does not know. */
+type LambderContractInputOf<TContract, TApiName> = IsAny<TContract> extends true ? any : TApiName extends keyof TContract ? TContract[TApiName] extends {
+    input: infer TInput;
+} ? TInput : any : any;
+/** The output type one API of a contract declares; `any` for an untyped caller or a name the contract does not know. */
+export type LambderContractOutputOf<TContract, TApiName> = IsAny<TContract> extends true ? any : TApiName extends keyof TContract ? TContract[TApiName] extends {
+    output: infer TOutput;
+} ? TOutput : any : any;
+type GuardInputsOf<TEntry> = TEntry extends {
+    guardInputs: infer G;
+} ? G : never;
+/** Input type of guard G on one contract entry; never when that API does not declare it. */
+type GuardInputOf<TEntry, G extends string> = GuardInputsOf<TEntry> extends infer I ? (G extends keyof I ? I[G] : never) : never;
+/**
+ * What guardInputsProvider returns: for every provided guard name, the value
+ * the contract's APIs expect for it (a union across APIs when they differ).
+ * Naming a guard no API declares in guardInput mode resolves to never, so a
+ * typo fails the provider's return type instead of going missing at runtime.
+ */
+export type LambderProvidedGuardInputs<TContract, TProvided extends string> = IsAny<TContract> extends true ? Record<TProvided, unknown> : {
+    [G in TProvided]: {
+        [K in keyof TContract]: GuardInputOf<TContract[K], G>;
+    }[keyof TContract];
+};
+/**
+ * Supplies guardInputs for every call from one place (the organization the
+ * UI is on, a device token), keyed by guard name; per-call guardInputs
+ * merge on top. Name the guards it covers in the caller's second type
+ * parameter, `new LambderCaller<Contract, "orgPermission">`, and calls to
+ * APIs whose guardInput guards are all covered do not require the
+ * options argument. May be async; a throw fails the call as an unknown
+ * error before anything is sent.
+ */
+export type LambderGuardInputsProvider<TContract, TProvided extends string> = (apiName: keyof TContract & string) => LambderProvidedGuardInputs<TContract, TProvided> | Promise<LambderProvidedGuardInputs<TContract, TProvided>>;
+/** Optional until the caller names provided guards: naming them without a provider would send nothing. */
+export type LambderGuardInputsProviderOption<TContract, TProvided extends string> = [
+    TProvided
+] extends [never] ? {
+    guardInputsProvider?: LambderGuardInputsProvider<TContract, TProvided>;
+} : {
+    guardInputsProvider: LambderGuardInputsProvider<TContract, TProvided>;
+};
+/** An API's guardInput guards the provider does not cover: those the call must still pass. */
+type RemainingGuardInputs<TEntry, TProvided extends string> = Omit<GuardInputsOf<TEntry>, TProvided>;
+/**
+ * The guardInputs field of one API's options: absent when its guards take no
+ * client input, optional when the provider covers every one of them (they may
+ * still be overridden per call), and mandatory with the uncovered ones spelled
+ * out otherwise.
+ */
+type ContractGuardInputsField<TEntry, TProvided extends string> = [
+    GuardInputsOf<TEntry>
+] extends [never] ? {} : [keyof RemainingGuardInputs<TEntry, TProvided>] extends [never] ? {
+    guardInputs?: Partial<GuardInputsOf<TEntry>>;
+} : {
+    guardInputs: RemainingGuardInputs<TEntry, TProvided> & Partial<GuardInputsOf<TEntry>>;
+};
+/**
+ * The idempotencyKey field of one API's options: mandatory once the entry
+ * declares `idempotency`, absent otherwise.
+ *
+ * Read as "required unless it says false" rather than "required only when it
+ * says true", so an entry whose option widened to `boolean` (declared through
+ * a spread, or built in a helper) keeps the requirement instead of quietly
+ * losing its compile-time half.
+ */
+type ContractIdempotencyKeyField<TContract, TApiName> = TApiName extends keyof TContract ? [LambderContractIdempotencyOf<TContract, TApiName>] extends [never] ? {} : [LambderContractIdempotencyOf<TContract, TApiName>] extends [false] ? {} : {
+    idempotencyKey: string;
+} : {};
+/**
+ * What the contract adds to one call's options: the guardInputs field and the
+ * idempotencyKey field, each decided by what the API's entry declares.
+ */
+type ContractCallFields<TContract, TApiName, TProvided extends string> = TApiName extends keyof TContract ? ContractGuardInputsField<TContract[TApiName], TProvided> & ContractIdempotencyKeyField<TContract, TApiName> : {};
+/**
+ * The options argument of one call: optional normally, REQUIRED when the
+ * contract demands something of it, so forgetting a guard's value or an
+ * idempotent API's key is a compile error at the call site rather than a 422
+ * from the server or a replay that never happens. TOptions is the caller's own
+ * per-call options type; the contract's fields are layered on top of it.
+ *
+ * `{} extends TFields` is the question "is every field the contract added
+ * optional": an empty object is assignable to a type whose properties are all
+ * optional and to nothing else.
+ */
+type LambderCallOptionsArg<TContract, TApiName, TProvided extends string, TOptions extends {
+    guardInputs?: Record<string, unknown>;
+}> = IsAny<TContract> extends true ? [options?: TOptions] : TApiName extends keyof TContract ? ContractCallFields<TContract, TApiName, TProvided> extends infer TFields ? {} extends TFields ? [options?: TOptions & TFields] : [options: TOptions & TFields] : never : [options?: TOptions];
+/**
+ * Everything one call passes after the API name: the payload, then the
+ * options, both decided by the contract.
+ *
+ * The payload is optional only when the API's input accepts undefined, so
+ * `caller.api("getUser")` against `input: { id: string }` is a compile error
+ * at the call site rather than a 422 from the server. Building it as one rest
+ * tuple is what makes that possible: a plain optional parameter cannot be
+ * made mandatory by a later type, and TypeScript has no per-argument
+ * conditional otherwise.
+ *
+ * When the options argument is itself mandatory (an uncovered guardInput
+ * guard, an idempotent API's key), the payload cannot stay optional in front
+ * of it, since a tuple's required element may not follow an optional one.
+ * Such a call passes its payload explicitly, `undefined` included.
+ */
+export type LambderCallArgs<TContract, TApiName, TProvided extends string, TOptions extends {
+    guardInputs?: Record<string, unknown>;
+}> = LambderCallOptionsArg<TContract, TApiName, TProvided, TOptions> extends [options: infer TRequired] ? [payload: LambderContractInputOf<TContract, TApiName>, options: TRequired] : LambderCallOptionsArg<TContract, TApiName, TProvided, TOptions> extends [options?: infer TOptional] ? undefined extends LambderContractInputOf<TContract, TApiName> ? [payload?: LambderContractInputOf<TContract, TApiName>, options?: TOptional] : [payload: LambderContractInputOf<TContract, TApiName>, options?: TOptional] : never;
+/**
+ * Provider values underneath, per-call values on top; undefined when neither
+ * side supplied any. Synchronous on purpose: a caller awaits its provider
+ * only when it has one, so a call without a provider still issues its
+ * request in the same tick it was made.
+ */
+export declare const mergeGuardInputs: (provided: Record<string, unknown> | undefined, perCall: Record<string, unknown> | undefined) => Record<string, unknown> | undefined;
+export {};

package/dist/shared/wire/LambderCallOptions.js

@@ -0,0 +1,17 @@
+/**
+ * The per-call options both callers take, the contract-driven typing of a
+ * call's arguments, and the runtime merge of guard inputs, shared by the
+ * browser caller (LambderCaller) and the server-side invoke caller
+ * (LambderInvokeCaller). Both speak the same envelope to the same kind of
+ * contract, so what an API demands of its caller (a guardInput-mode guard's
+ * value, say) is decided here once and the two callers cannot drift on it.
+ * Pure types and one dependency-free function, so the browser entry resolves
+ * it.
+ */
+/**
+ * Provider values underneath, per-call values on top; undefined when neither
+ * side supplied any. Synchronous on purpose: a caller awaits its provider
+ * only when it has one, so a call without a provider still issues its
+ * request in the same tick it was made.
+ */
+export const mergeGuardInputs = (provided, perCall) => provided !== undefined || perCall !== undefined ? { ...provided, ...perCall } : undefined;

package/dist/shared/{LambderCompressionCodec.d.ts → wire/LambderCompressionCodec.d.ts}

@@ -1,7 +1,7 @@
 /**
  * The one place Lambder compresses and decompresses bytes.
  *
- * Five things compress: sessions, LambderDdbCache and LambderDdbIdempotency
+ * Five things compress: sessions, LambderDdbCache and LambderDdbIdempotencyStore
  * (Brotli at rest in DynamoDB), HTTP responses (Brotli or gzip, negotiated)
  * and request payloads (gzip from a browser, whose CompressionStream offers
  * nothing else; Brotli from a Node caller). They all compress text, so TEXT
@@ -21,11 +21,15 @@
  * implementation: a bug fixed here is fixed for records at rest and for
  * untrusted request bodies alike.
  *
- * zlib is loaded lazily through node-polyfills, so a module importing this
+ * zlib is loaded lazily through LambderNodeModules, so a module importing this
  * one can still sit in a frontend bundle's import graph via the package
- * root. The option that decides WHETHER to compress, and the encoding
- * vocabulary, live in LambderCompressionOption, which stays free of zlib
- * entirely so the browser entry can resolve it.
+ * root. Compressing needs zlib and is server-side; restoring runs anywhere,
+ * through zlib where it exists and through the web DecompressionStream
+ * otherwise, so the API core can restore a gzipped request payload in a
+ * browser (the mock runtime) under the same bound. The option that decides
+ * WHETHER to compress, and the encoding vocabulary, live in
+ * LambderCompressionOption, which stays free of zlib entirely so the browser
+ * entry can resolve it.
  */
 import type { LambderEncoding } from "./LambderCompressionOption.js";
 /** Why a bounded restore failed, for callers that answer rather than throw. */
@@ -81,7 +85,7 @@ export type LambderRestoreBound = {
  * UTF-8 decode; going through a string would replace every byte that is not
  * valid UTF-8 and hand back a body that is silently not what was sent.
  */
-export declare const restoreBytes: (compressed: Uint8Array, encoding: LambderEncoding, bound: LambderRestoreBound) => Promise<Buffer>;
+export declare const restoreBytes: (compressed: Uint8Array, encoding: LambderEncoding, bound: LambderRestoreBound) => Promise<Uint8Array>;
 /**
  * Restores text: restoreBytes plus the UTF-8 decode. What every text caller
  * uses (sessions, the DynamoDB stores, request payloads). The declared byte

package/dist/shared/{LambderCompressionCodec.js → wire/LambderCompressionCodec.js}

@@ -1,7 +1,7 @@
 /**
  * The one place Lambder compresses and decompresses bytes.
  *
- * Five things compress: sessions, LambderDdbCache and LambderDdbIdempotency
+ * Five things compress: sessions, LambderDdbCache and LambderDdbIdempotencyStore
  * (Brotli at rest in DynamoDB), HTTP responses (Brotli or gzip, negotiated)
  * and request payloads (gzip from a browser, whose CompressionStream offers
  * nothing else; Brotli from a Node caller). They all compress text, so TEXT
@@ -21,13 +21,18 @@
  * implementation: a bug fixed here is fixed for records at rest and for
  * untrusted request bodies alike.
  *
- * zlib is loaded lazily through node-polyfills, so a module importing this
+ * zlib is loaded lazily through LambderNodeModules, so a module importing this
  * one can still sit in a frontend bundle's import graph via the package
- * root. The option that decides WHETHER to compress, and the encoding
- * vocabulary, live in LambderCompressionOption, which stays free of zlib
- * entirely so the browser entry can resolve it.
+ * root. Compressing needs zlib and is server-side; restoring runs anywhere,
+ * through zlib where it exists and through the web DecompressionStream
+ * otherwise, so the API core can restore a gzipped request payload in a
+ * browser (the mock runtime) under the same bound. The option that decides
+ * WHETHER to compress, and the encoding vocabulary, live in
+ * LambderCompressionOption, which stays free of zlib entirely so the browser
+ * entry can resolve it.
  */
-import { getZlib } from "./node-polyfills.js";
+import { getZlib } from "../util/LambderNodeModules.js";
+import { assertPositiveInteger } from "../util/LambderOptionChecks.js";
 /** Why a bounded restore failed, for callers that answer rather than throw. */
 export const LAMBDER_RESTORE_FAILURES = {
     /** The declared byte length is absent or not a positive integer. */
@@ -103,27 +108,22 @@ export const compressText = async (input, encoding, quality) => {
 export const restoreBytes = async (compressed, encoding, bound) => {
     const verified = "declaredBytes" in bound;
     const limit = verified ? bound.declaredBytes : bound.maxBytes;
-    if (!Number.isSafeInteger(limit) || limit <= 0) {
-        if (verified) {
+    if (verified) {
+        // A declared length comes off the wire, so a bad one is a bad request
+        // with a reason a caller can be told, not a configuration error.
+        if (!Number.isSafeInteger(limit) || limit <= 0) {
             throw new LambderCompressionError(LAMBDER_RESTORE_FAILURES.missingLength, "compressed value is missing its byte length");
         }
-        throw new Error("restoreBytes: maxBytes must be a positive integer");
     }
-    const zlib = await requireZlib();
+    else {
+        assertPositiveInteger(limit, "restoreBytes maxBytes");
+    }
+    const zlib = await getZlib();
     let output;
     try {
-        // zlib reads any Uint8Array in place; a request-sized body is not copied first.
-        output = await new Promise((resolve, reject) => {
-            const done = (error, result) => { if (error)
-                reject(error);
-            else
-                resolve(result); };
-            // maxOutputLength is the bound: zlib stops rather than allocating past it.
-            if (encoding === "br")
-                zlib.brotliDecompress(compressed, { maxOutputLength: limit }, done);
-            else
-                zlib.gunzip(compressed, { maxOutputLength: limit }, done);
-        });
+        output = zlib
+            ? await restoreWithZlib(zlib, compressed, encoding, limit)
+            : await restoreWithWebStreams(compressed, encoding, limit);
     }
     catch (err) {
         throw new LambderCompressionError(LAMBDER_RESTORE_FAILURES.undecodable, "compressed value could not be decompressed", { cause: err });
@@ -140,4 +140,48 @@ export const restoreBytes = async (compressed, encoding, bound) => {
  * which is the restored buffer's length, so the verification is the same one
  * either way.
  */
-export const restoreText = async (compressed, encoding, bound) => (await restoreBytes(compressed, encoding, bound)).toString("utf8");
+export const restoreText = async (compressed, encoding, bound) => new TextDecoder().decode(await restoreBytes(compressed, encoding, bound));
+/** zlib reads any Uint8Array in place; maxOutputLength is the bound, so it stops rather than allocating past it. */
+const restoreWithZlib = (zlib, compressed, encoding, limit) => new Promise((resolve, reject) => {
+    const done = (error, result) => { if (error)
+        reject(error);
+    else
+        resolve(result); };
+    if (encoding === "br")
+        zlib.brotliDecompress(compressed, { maxOutputLength: limit }, done);
+    else
+        zlib.gunzip(compressed, { maxOutputLength: limit }, done);
+});
+/**
+ * The browser's restore: DecompressionStream, read chunk by chunk and cut
+ * off past the bound, which is the one thing the stream API does not do on
+ * its own. Brotli arrives here only where the runtime offers it; a runtime
+ * without it rejects the format, which reads as undecodable.
+ */
+const restoreWithWebStreams = async (compressed, encoding, limit) => {
+    if (typeof DecompressionStream === "undefined")
+        throw new Error("Lambder compression requires zlib or DecompressionStream.");
+    const format = (encoding === "br" ? "br" : "gzip");
+    const bytes = new Uint8Array(compressed);
+    const reader = new Blob([bytes]).stream().pipeThrough(new DecompressionStream(format)).getReader();
+    const chunks = [];
+    let total = 0;
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        total += value.length;
+        if (total > limit) {
+            await reader.cancel();
+            throw new Error("decompressed output exceeds the bound");
+        }
+        chunks.push(value);
+    }
+    const output = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of chunks) {
+        output.set(chunk, offset);
+        offset += chunk.length;
+    }
+    return output;
+};

package/dist/shared/{LambderCompressionOption.d.ts → wire/LambderCompressionOption.d.ts}

@@ -3,7 +3,7 @@
  * that resolves it.
  *
  * Five places compress something: sessions, LambderDdbCache and
- * LambderDdbIdempotency (Brotli at rest in DynamoDB), HTTP responses
+ * LambderDdbIdempotencyStore (Brotli at rest in DynamoDB), HTTP responses
  * (Brotli/gzip on the wire) and request payloads (gzip on the wire). They
  * differ in what they can be tuned with, so each declares its own settings
  * type, but they share one vocabulary and one resolution: `true` is on with

package/dist/shared/{LambderCompressionOption.js → wire/LambderCompressionOption.js}

@@ -3,7 +3,7 @@
  * that resolves it.
  *
  * Five places compress something: sessions, LambderDdbCache and
- * LambderDdbIdempotency (Brotli at rest in DynamoDB), HTTP responses
+ * LambderDdbIdempotencyStore (Brotli at rest in DynamoDB), HTTP responses
  * (Brotli/gzip on the wire) and request payloads (gzip on the wire). They
  * differ in what they can be tuned with, so each declares its own settings
  * type, but they share one vocabulary and one resolution: `true` is on with
@@ -16,6 +16,7 @@
  * option without pulling Node built-ins into the bundle; the compression
  * primitives themselves live in LambderCompressionCodec, which does load zlib.
  */
+import { assertNonNegativeInteger } from "../util/LambderOptionChecks.js";
 /** Algorithms Lambder can produce. Brotli at rest and preferred on responses; gzip everywhere a browser has to do the compressing. */
 export const LAMBDER_ENCODINGS = ["br", "gzip"];
 /**
@@ -37,9 +38,7 @@ export const resolveCompressionOption = (option, defaults) => {
     const config = option === true || option === undefined ? {} : option;
     const overrides = Object.fromEntries(Object.entries(config).filter(([, value]) => value !== undefined));
     const settings = { ...defaults, ...overrides };
-    if (!Number.isSafeInteger(settings.minBytes) || settings.minBytes < 0) {
-        throw new Error("compression.minBytes must be a non-negative integer");
-    }
+    assertNonNegativeInteger(settings.minBytes, "compression.minBytes");
     if (settings.quality !== undefined && (!Number.isInteger(settings.quality) || settings.quality < 0 || settings.quality > 11)) {
         throw new Error("compression.quality must be an integer from 0 to 11");
     }

package/dist/shared/{LambderCrashDetail.d.ts → wire/LambderCrashDetail.d.ts}

@@ -46,3 +46,13 @@ export declare const describeCrash: (error: unknown, ctx?: {
  * causes see the callee's stack as it was.
  */
 export declare const errorFromCrashDetail: (crash: LambderCrashDetail) => Error;
+/**
+ * A thrown value as an Error, so a reporter or a `cause` chain always holds
+ * one. An Error passes through; anything else becomes an Error whose message
+ * describes the value the way describeCrash does, JSON where String() cannot
+ * (a null-prototype object or a throwing toString must not make the
+ * coercion itself throw). One implementation, rather than
+ * `err instanceof Error ? err : new Error(...)` spelled at every site with a
+ * fallback of its own.
+ */
+export declare const coerceToError: (value: unknown, fallbackMessage?: string) => Error;