lambder 6.0.2 → 7.0.1

package/dist/shared/LambderApiOutcome.d.ts

@@ -1,69 +0,0 @@
-/**
- * The one mapping from an HTTP answer to an API outcome.
- *
- * LambderCaller (a browser, over fetch) and LambderInvokeCaller (a server,
- * over a direct Lambda invoke) receive the same envelope and must read it
- * the same way: which status is a crash, which is a rejected input, in what
- * order the envelope flags are honoured, what a non-envelope body means.
- * Both hand their answer to resolveApiOutcome and act on the result; the
- * side effects each has (handlers, cookie clearing, error reporting) stay
- * with the caller that owns them. Pure and dependency-free, so the browser
- * entry resolves it.
- */
-import type { z } from "zod";
-import type { LambderApiResponse } from "./LambderApiContract.js";
-/**
- * The 422 body's `zodError` as it survives JSON: a ZodError's name and
- * message, and its issues spelled out. Not a ZodError instance (it has no
- * methods on this side of the wire), which is why it is not typed as one.
- */
-export type LambderValidationError = {
-    name: string;
-    message: string;
-    issues: z.core.$ZodIssue[];
-};
-export type LambderApiFailureReason = 'network' | 'timeout' | 'server' | 'validation' | 'versionExpired' | 'sessionExpired' | 'notAuthorized' | 'errorMessage' | 'unknown';
-/**
- * Discriminated result of an API call: `ok: true` carries the payload, every
- * failure carries a machine-readable reason, so "the server returned null"
- * and "the request failed" are never conflated.
- */
-export type LambderApiOutcome<T> = {
-    ok: true;
-    payload: T | null | undefined;
-    response: LambderApiResponse<T>;
-} | {
-    ok: false;
-    reason: LambderApiFailureReason;
-    /** HTTP status, when a response was received. */
-    status?: number;
-    /** Envelope errorMessage, when the server provided one. */
-    errorMessage?: any;
-    /** Seconds to wait before retrying, from the response's Retry-After header (rate-limit refusals send it). */
-    retryAfterSeconds?: number;
-    /** Underlying Error for network/timeout/server/unknown failures. */
-    error?: Error;
-    /** The issues for 'validation'. */
-    zodError?: LambderValidationError;
-    /** The parsed envelope, when one was received (protocol-level failures, and a 5xx that answered with Lambder's own envelope). */
-    response?: LambderApiResponse<T>;
-};
-/** What the mapping needs from an HTTP answer, whichever transport produced it. */
-export type LambderApiHttpAnswer = {
-    status: number;
-    statusText?: string;
-    /** Case-insensitive header lookup; null or undefined when absent. */
-    header: (name: string) => string | null | undefined;
-    /** The body parsed as JSON; rejects when it is not JSON. */
-    json: () => Promise<unknown>;
-    /** The body as text. */
-    text: () => Promise<string>;
-};
-/**
- * Reads one HTTP answer into an outcome. A 5xx is a server failure that keeps
- * the envelope when the server sent one (Lambder's own 500 body carries
- * errorMessage, and a global error handler may add crash and logList); a
- * 422 is a validation failure only with Lambder's validation body; anything
- * else must be a JSON envelope, whose flags are honoured in a fixed order.
- */
-export declare const resolveApiOutcome: <T>(answer: LambderApiHttpAnswer) => Promise<LambderApiOutcome<T>>;

package/dist/shared/LambderCallOptions.d.ts

@@ -1,71 +0,0 @@
-/**
- * The contract-driven typing of a call's options argument, 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.
- */
-export type IsAny<T> = 0 extends (1 & T) ? true : false;
-export 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 no longer 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 options argument of one call: optional normally, REQUIRED (with
- * guardInputs) when the API's contract declares guardInput-mode guards the
- * provider does not cover, so forgetting to send a guard's value is a
- * compile error at the call site. Provided guards may still be overridden
- * per call. TOptions is the caller's own per-call options type; the
- * guardInputs requirement is layered on top of it.
- */
-export type LambderCallOptionsArg<TContract, TApiName, TProvided extends string, TOptions extends {
-    guardInputs?: Record<string, unknown>;
-}> = IsAny<TContract> extends true ? [options?: TOptions] : TApiName extends keyof TContract ? [GuardInputsOf<TContract[TApiName]>] extends [never] ? [options?: TOptions] : [keyof RemainingGuardInputs<TContract[TApiName], TProvided>] extends [never] ? [options?: TOptions & {
-    guardInputs?: Partial<GuardInputsOf<TContract[TApiName]>>;
-}] : [
-    options: TOptions & {
-        guardInputs: RemainingGuardInputs<TContract[TApiName], TProvided> & Partial<GuardInputsOf<TContract[TApiName]>>;
-    }
-] : [options?: TOptions];
-/**
- * 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/LambderCallOptions.js

@@ -1,16 +0,0 @@
-/**
- * The contract-driven typing of a call's options argument, 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/node-polyfills.d.ts

@@ -1,4 +0,0 @@
-export declare function getFS(): Promise<typeof import('fs') | null>;
-export declare function getPath(): Promise<typeof import('path') | null>;
-export declare function getZlib(): Promise<typeof import('zlib') | null>;
-export declare function getCrypto(): Promise<typeof import('crypto') | null>;

package/dist/shared/node-polyfills.js

@@ -1,58 +0,0 @@
-// Node.js polyfills for browser compatibility
-// This file provides optional Node.js modules that fail gracefully in browser environments
-let fs = null;
-let path = null;
-let zlib = null;
-let crypto = null;
-export async function getFS() {
-    try {
-        if (fs) {
-            return fs;
-        }
-        fs = await import('fs');
-        return fs;
-    }
-    catch (e) {
-        // Silently fail - we're in a browser environment
-        return null;
-    }
-}
-export async function getPath() {
-    try {
-        if (path) {
-            return path;
-        }
-        path = await import('path');
-        return path;
-    }
-    catch (e) {
-        // Silently fail - we're in a browser environment
-        return null;
-    }
-}
-export async function getZlib() {
-    try {
-        if (zlib) {
-            return zlib;
-        }
-        zlib = await import('zlib');
-        return zlib;
-    }
-    catch (e) {
-        // Silently fail - we're in a browser environment
-        return null;
-    }
-}
-export async function getCrypto() {
-    try {
-        if (crypto) {
-            return crypto;
-        }
-        crypto = await import('crypto');
-        return crypto;
-    }
-    catch (e) {
-        // Silently fail - we're in a browser environment
-        return null;
-    }
-}

package/dist/stores/LambderDdbIdempotency.js

@@ -1,229 +0,0 @@
-import crypto from "crypto";
-import { loadDynamoClientSdk } from "./LambderDdbSdk.js";
-import { compressText, restoreText } from "../shared/LambderCompressionCodec.js";
-import { resolveCompressionOption, } from "../shared/LambderCompressionOption.js";
-/** Bodies of 1KB or more are stored Brotli-compressed by default; smaller ones stay plain. */
-const COMPRESSION_DEFAULTS = { minBytes: 1024, quality: 5 };
-/**
- * Stored-body budget inside DynamoDB's 400KB item limit (headers, keys and
- * attributes need headroom). Applies to the bytes actually stored, so a
- * large compressible response (JSON usually shrinks 5-10x) still replays.
- */
-const MAX_STORED_BODY_BYTES = 350_000;
-/**
- * DynamoDB-backed idempotency records: one item per (identity, api, key)
- * scope, claimed atomically with a conditional put. The first request claims
- * the scope as "pending"; concurrent duplicates see "pending"; once the
- * response is stored via complete(), replays get it back verbatim until the
- * TTL. Records whose expiresAt has passed count as absent (DynamoDB TTL
- * deletion is lazy, so expiry is enforced in the condition, not left to TTL).
- *
- * Every claim carries a random ownerToken, and complete()/abandon() are
- * conditional on still holding it: an original that outlives its pending TTL
- * and loses the scope to a retry can no longer overwrite or delete the
- * retry's claim (both settle calls become silent no-ops instead).
- *
- * Stored bodies are Brotli-compressed from 1KB by default (same scheme as
- * LambderDdbCache, see the `compression` option): the bodies are JSON
- * envelopes that typically shrink 5-10x, which cuts DynamoDB write units
- * and lets large responses fit the item budget instead of skipping replay
- * storage.
- *
- * Table shape: string hash key `pk`, string range key `sk`, TTL on
- * `expiresAt`. Items are prefixed `IDEM#` by default, so the table can be
- * shared with LambderDdbRateLimiter (`RL#`) and LambderDdbCache (`CACHE#`)
- * without key collisions.
- */
-export class LambderDdbIdempotency {
-    tableName;
-    keyPrefix;
-    compression;
-    /** The client given at creation, or one created from `region` on first use; the SDK arrives with it. */
-    providedClient;
-    region;
-    readyPromise;
-    constructor(options) {
-        if (!options.tableName.trim())
-            throw new Error("tableName is required");
-        this.tableName = options.tableName;
-        this.keyPrefix = options.keyPrefix ?? "IDEM";
-        this.compression = resolveCompressionOption(options.compression, COMPRESSION_DEFAULTS);
-        this.providedClient = options.client;
-        this.region = options.region;
-    }
-    /** The SDK and the client, loaded and created the first time the table is touched (see LambderDdbSdk). */
-    ready() {
-        this.readyPromise ??= loadDynamoClientSdk("LambderDdbIdempotency")
-            .then((sdk) => ({ sdk, client: this.providedClient ?? new sdk.DynamoDBClient(this.region ? { region: this.region } : {}) }))
-            .catch((error) => { this.readyPromise = undefined; throw error; });
-        return this.readyPromise;
-    }
-    itemKey(scopeKey) {
-        return { pk: { S: `${this.keyPrefix}#${scopeKey}` }, sk: { S: "idem" } };
-    }
-    /** Parse a stored item's response headers. */
-    static readItemHeaders(item) {
-        const raw = item.headersJson?.S;
-        if (!raw)
-            return {};
-        try {
-            const parsed = JSON.parse(raw);
-            if (parsed && typeof parsed === "object")
-                return parsed;
-        }
-        catch { /* corrupt record: replay with no headers rather than fail */ }
-        return {};
-    }
-    /** A stored item's response body: plain (`body`) or Brotli (`bodyBr` + `bodyBytes`). */
-    static async readItemBody(item) {
-        const compressed = item.bodyBr?.B;
-        if (compressed)
-            return await restoreText(compressed, "br", { declaredBytes: Number(item.bodyBytes?.N ?? 0) });
-        return item.body?.S ?? "";
-    }
-    /**
-     * Read the scope without claiming it: the stored response when a
-     * completed, unexpired record exists, null otherwise (absent, pending, or
-     * expired). Eventually-consistent read: a miss here only means the caller
-     * proceeds to begin(), whose read is authoritative.
-     */
-    async peek(scopeKey) {
-        const { client, sdk } = await this.ready();
-        const existing = await client.send(new sdk.GetItemCommand({
-            TableName: this.tableName,
-            Key: this.itemKey(scopeKey),
-        }));
-        const item = existing.Item;
-        if (!item || item.state?.S !== "done")
-            return null;
-        const nowSeconds = Math.floor(Date.now() / 1000);
-        if (Number(item.expiresAt?.N ?? 0) <= nowSeconds)
-            return null;
-        return {
-            statusCode: Number(item.statusCode?.N ?? 200),
-            headers: LambderDdbIdempotency.readItemHeaders(item),
-            body: await LambderDdbIdempotency.readItemBody(item),
-        };
-    }
-    /**
-     * Claim the scope. "new" means this request now owns it (proven by the
-     * returned ownerToken) and must call complete() or abandon(); "pending"
-     * means another request owns it right now; "done" carries the stored
-     * response to replay.
-     */
-    async begin(scopeKey, { pendingTtlSeconds }) {
-        const nowSeconds = Math.floor(Date.now() / 1000);
-        const ownerToken = crypto.randomBytes(16).toString("hex");
-        try {
-            const { client, sdk } = await this.ready();
-            await client.send(new sdk.PutItemCommand({
-                TableName: this.tableName,
-                Item: {
-                    ...this.itemKey(scopeKey),
-                    state: { S: "pending" },
-                    ownerToken: { S: ownerToken },
-                    expiresAt: { N: String(nowSeconds + pendingTtlSeconds) },
-                },
-                ConditionExpression: "attribute_not_exists(pk) OR expiresAt <= :now",
-                ExpressionAttributeValues: { ":now": { N: String(nowSeconds) } },
-            }));
-            return { state: "new", ownerToken };
-        }
-        catch (error) {
-            if (error.name !== "ConditionalCheckFailedException")
-                throw error;
-        }
-        const { client, sdk } = await this.ready();
-        const existing = await client.send(new sdk.GetItemCommand({
-            TableName: this.tableName,
-            Key: this.itemKey(scopeKey),
-            ConsistentRead: true,
-        }));
-        const item = existing.Item;
-        // Deleted between the put and the read: treat as in-flight, the retry resolves it.
-        if (!item)
-            return { state: "pending" };
-        if (item.state?.S === "done") {
-            return {
-                state: "done",
-                statusCode: Number(item.statusCode?.N ?? 200),
-                headers: LambderDdbIdempotency.readItemHeaders(item),
-                body: await LambderDdbIdempotency.readItemBody(item),
-            };
-        }
-        return { state: "pending" };
-    }
-    /**
-     * Store the response for replays, overwriting the pending claim. Bodies
-     * from the compression option's minBytes are stored Brotli-compressed
-     * (they are JSON envelopes, which typically shrink 5-10x), cutting
-     * DynamoDB write units and letting large responses fit the item budget;
-     * smaller bodies, or all of them with compression off, stay plain.
-     * Returns:
-     *
-     * - "stored": the record is in place and will replay.
-     * - "too-large": even compressed, the body exceeds the item budget;
-     *   nothing was written and the caller should release the claim.
-     * - "lost": the ownerToken no longer matches, i.e. the claim expired and
-     *   a retry took the scope over; nothing was written.
-     */
-    async complete(scopeKey, ownerToken, { statusCode, headers, body, ttlSeconds }) {
-        const nowSeconds = Math.floor(Date.now() / 1000);
-        const rawBody = Buffer.from(body, "utf8");
-        let bodyAttributes;
-        if (this.compression && rawBody.byteLength >= this.compression.minBytes) {
-            const compressed = await compressText(rawBody, "br", this.compression.quality);
-            if (compressed.byteLength > MAX_STORED_BODY_BYTES)
-                return "too-large";
-            // bodyBytes bounds and verifies decompression on read.
-            bodyAttributes = { bodyBr: { B: compressed }, bodyBytes: { N: String(rawBody.byteLength) } };
-        }
-        else {
-            bodyAttributes = { body: { S: body } };
-        }
-        try {
-            const { client, sdk } = await this.ready();
-            await client.send(new sdk.PutItemCommand({
-                TableName: this.tableName,
-                Item: {
-                    ...this.itemKey(scopeKey),
-                    state: { S: "done" },
-                    ownerToken: { S: ownerToken },
-                    statusCode: { N: String(statusCode) },
-                    headersJson: { S: JSON.stringify(headers) },
-                    ...bodyAttributes,
-                    expiresAt: { N: String(nowSeconds + ttlSeconds) },
-                },
-                ConditionExpression: "ownerToken = :owner",
-                ExpressionAttributeValues: { ":owner": { S: ownerToken } },
-            }));
-            return "stored";
-        }
-        catch (error) {
-            if (error.name !== "ConditionalCheckFailedException")
-                throw error;
-            return "lost";
-        }
-    }
-    /**
-     * Release the claim without storing a response (crash, uncacheable
-     * response), so a retry can execute. Conditional on still holding the
-     * claim; a lost claim makes this a silent no-op.
-     */
-    async abandon(scopeKey, ownerToken) {
-        try {
-            const { client, sdk } = await this.ready();
-            await client.send(new sdk.DeleteItemCommand({
-                TableName: this.tableName,
-                Key: this.itemKey(scopeKey),
-                ConditionExpression: "ownerToken = :owner",
-                ExpressionAttributeValues: { ":owner": { S: ownerToken } },
-            }));
-        }
-        catch (error) {
-            if (error.name !== "ConditionalCheckFailedException")
-                throw error;
-        }
-    }
-}
-export default LambderDdbIdempotency;

package/dist/testing.d.ts

@@ -1,9 +0,0 @@
-/**
- * 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

@@ -1,8 +0,0 @@
-/**
- * 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";