lambder 11.1.1 → 13.0.1

package/dist/mock.d.ts

@@ -9,7 +9,7 @@
 export { LambderMockApp, initLambderMock } from "./mock/LambderMockApp.js";
 export { LambderMockTransportError } from "./mock/LambderMockFailureInjector.js";
 export type { LambderMockAppOptions, LambderMockSessionsOptions, LambderMockIdempotencyOptions, LambderMockInvalidInputAnswer, LambderMockTransport, LambderMockTransportOptions } from "./mock/LambderMockCreateOptions.js";
-export type { LambderMockCallContext, LambderMockSessionCallContext, LambderMockContext, LambderMockRefusalsOf, LambderMockGuards, LambderMockHandler, LambderMockEntry, LambderMockEntryOptions, LambderMockEntryInput, LambderMockSlice, LambderMockRestEntry, LambderMockRegistryCheck, LambderMockMissingNames, LambderMockStrayNames, LambderMockDuplicateNames, LambderMockPublicNames, LambderMockSessionNames, LambderMockLatency, LambderMockFailure, LambderMockFailureReason, LambderMockOutcome, LambderMockCallEvent, LambderMockRequestEvent, LambderMockResponseEvent, LambderMockCallRecord, LambderMockListener, LambderMockRateLimitPolicies, LambderMockInputOf, LambderMockOutputOf, LambderMockOverride, } from "./mock/LambderMockTypes.js";
+export type { LambderMockCallContext, LambderMockSessionCallContext, LambderMockContext, LambderMockRefusalsOf, LambderMockGuards, LambderMockHandler, LambderMockEntry, LambderMockEntryOptions, LambderMockEntryInput, LambderMockNotMockedInput, LambderMockSessionGuardsCheck, LambderMockSlice, LambderMockRestEntry, LambderMockRegistryCheck, LambderMockMissingNames, LambderMockStrayNames, LambderMockDuplicateNames, LambderMockLatency, LambderMockFailure, LambderMockFailureReason, LambderMockOutcome, LambderMockCallEvent, LambderMockRequestEvent, LambderMockResponseEvent, LambderMockCallRecord, LambderMockListener, LambderMockRateLimitPolicies, LambderMockInputOf, LambderMockOutputOf, LambderMockOverride, } from "./mock/LambderMockTypes.js";
 export { lambderMockPoliciesFrom } from "./mock/lambderMockPoliciesFrom.js";
 export type { LambderCustomKeyedPolicyNames, LambderMockPolicyKeys } from "./mock/lambderMockPoliciesFrom.js";
 export type { LambderMockGuardShapeOf } from "./mock/LambderMockCreateOptions.js";
@@ -21,7 +21,7 @@ export { LambderMemoryUploadBucket } from "./stores/LambderMemoryUploadBucket.js
 export type { LambderMemoryUploadBucketOptions, LambderMemoryUploadObject } from "./stores/LambderMemoryUploadBucket.js";
 export { lambderMockUploadMswHandler } from "./mock/lambderMockUploadMswHandler.js";
 export { lambderMockInvokeTransport } from "./mock/lambderMockInvokeTransport.js";
-export type { LambderMockInvokeEvent, LambderMockInvokeResult } from "./mock/lambderMockInvokeTransport.js";
+export type { LambderMockInvokeEvent, LambderMockInvokeResult, LambderMockInvokeTransportOptions } from "./mock/lambderMockInvokeTransport.js";
 export { LambderCookieJar } from "./shared/transport/LambderCookieJar.js";
 export { lambderCookieJarTransport } from "./shared/transport/lambderCookieJarTransport.js";
 export type { LambderApiTransport, LambderApiTransportRequest } from "./shared/transport/LambderApiTransport.js";

package/dist/session/LambderSessionManager.d.ts

@@ -1,3 +1,4 @@
+import type { z } from "zod";
 import type { LambderSessionCrypto } from "./LambderSessionCrypto.js";
 import type { LambderSessionRecord, LambderSessionStore } from "../shared/contracts/LambderSessionStore.js";
 import { LAMBDER_BACKEND_SWAP } from "../shared/util/LambderTestingDoors.js";
@@ -60,6 +61,39 @@ export declare class LambderSessionDataRefreshError extends Error {
 export declare class LambderSessionReadError extends Error {
     constructor(cause: unknown);
 }
+/**
+ * The shape session.data has, and how it is kept fresh: `dataSchema` alone,
+ * or with `dataRefresh`, which then requires it.
+ *
+ * A record outlives the code that wrote it, so a read checks its data
+ * against the schema, and hands the request the schema's output (keys it
+ * does not declare stripped). Data that does not match (a record written
+ * before a deploy changed the data's shape) is refreshed on that read when
+ * dataRefresh is configured, whatever its deadline; without dataRefresh
+ * nothing can rebuild it, and the session ends. A refresh's own output is
+ * held to the schema too, and one that does not match fails the read as a
+ * LambderSessionDataRefreshError.
+ *
+ * Data is held to the schema where it is written as well: createSession and
+ * updateSessionData throw on data it refuses, rather than store a session
+ * whose next read would end it. What is stored is the data as given, and
+ * what a request is served is the schema's output, so every read of a
+ * record parses exactly what its write was checked with.
+ *
+ * Data a refresh derives from the app's state changes shape as the app
+ * does, which is why dataRefresh needs the schema: without it, a record
+ * written before the change is served in its old shape until its refresh
+ * comes due.
+ */
+export type LambderSessionDataOptions<SessionData = any> = {
+    /** The schema of session.data, checked on every read. */
+    dataSchema?: z.ZodType<SessionData>;
+    dataRefresh?: undefined;
+} | {
+    /** The schema of session.data, checked on every read and on every refresh's output. Required beside dataRefresh. */
+    dataSchema: z.ZodType<SessionData>;
+    dataRefresh: LambderSessionDataRefreshConfig<SessionData>;
+};
 export type LambderSessionManagerOptions<SessionData = any> = {
     /** Where sessions rest: LambderDdbSessionStore, LambderMemorySessionStore, or your own. */
     store: LambderSessionStore<SessionData>;
@@ -68,10 +102,9 @@ export type LambderSessionManagerOptions<SessionData = any> = {
     enableSlidingExpiration?: boolean;
     /** Min seconds between sliding-expiration writes. Default: max(60, 5% of TTL). */
     slidingWriteIntervalSeconds?: number;
-    dataRefresh?: LambderSessionDataRefreshConfig<SessionData>;
     /** Hashing and randomness. Default: WebCrypto. */
     crypto?: LambderSessionCrypto;
-};
+} & LambderSessionDataOptions<SessionData>;
 /**
  * Whether a string has the shape a minted session token has:
  * `sessionKeyHash:secret`, both hex, neither longer than 1024 characters.
@@ -105,8 +138,9 @@ export default class LambderSessionManager<SessionData = any> {
     private readonly enableSlidingExpiration;
     private readonly slidingWriteIntervalSeconds;
     private readonly dataRefresh;
+    private readonly dataSchema;
     private readonly crypto;
-    constructor({ store, sessionSalt, enableSlidingExpiration, slidingWriteIntervalSeconds, dataRefresh, crypto, }: LambderSessionManagerOptions<SessionData>);
+    constructor({ store, sessionSalt, enableSlidingExpiration, slidingWriteIntervalSeconds, dataRefresh, dataSchema, crypto, }: LambderSessionManagerOptions<SessionData>);
     /** A store this manager's crypto may sit in front of. Asked of every store it is given, the one at creation and a swapped one alike. */
     private assertCryptoFitsStore;
     /**
@@ -184,6 +218,15 @@ export default class LambderSessionManager<SessionData = any> {
      * logout, a password change), which a renewal must not undo.
      */
     renewSession(session: LambderSessionRecord<SessionData>): Promise<LambderSessionRecord<SessionData> | null>;
+    /**
+     * Data about to be stored, held to the schema: what a read of it will
+     * serve, or the error `refused` builds from where it does not match.
+     * Data the schema refuses is the app breaking its own declaration, and
+     * storing it would only move the failure to the next read, far from the
+     * code that wrote it. The data is stored as given, not as the schema's
+     * output, so every later read parses exactly what this check accepted.
+     */
+    private servedDataOf;
     /**
      * Runs the dataRefresh callback immediately, regardless of
      * dataExpiresAt, and persists the result onto the same record, over the

package/dist/session/LambderSessionManager.js

@@ -28,6 +28,11 @@ export class LambderSessionReadError extends Error {
         this.name = "LambderSessionReadError";
     }
 }
+/** A schema's issues as a message may show them: each path and what was expected there, never the value found. */
+const describeSchemaIssues = (error) => error.issues.slice(0, 5).map((issue) => `${issue.path.length ? issue.path.join(".") : "(the data)"}: ${issue.message}`).join("; ")
+    + (error.issues.length > 5 ? `; and ${error.issues.length - 5} more` : "");
+/** A refresh's output the schema refuses, as the read fails with it. */
+const refreshRefused = (issues) => new LambderSessionDataRefreshError(new Error(`the refreshed data does not match session.dataSchema (${issues})`));
 /**
  * The longest either half of a session token may be. A minted token is two
  * 64-character hex halves; sixteen times that leaves a custom
@@ -95,8 +100,9 @@ export default class LambderSessionManager {
     enableSlidingExpiration;
     slidingWriteIntervalSeconds;
     dataRefresh;
+    dataSchema;
     crypto;
-    constructor({ store, sessionSalt, enableSlidingExpiration = true, slidingWriteIntervalSeconds, dataRefresh, crypto, }) {
+    constructor({ store, sessionSalt, enableSlidingExpiration = true, slidingWriteIntervalSeconds, dataRefresh, dataSchema, crypto, }) {
         this.store = store;
         this.sessionSalt = sessionSalt;
         this.enableSlidingExpiration = enableSlidingExpiration;
@@ -105,7 +111,16 @@ export default class LambderSessionManager {
             : assertPositiveInteger(slidingWriteIntervalSeconds, "session.slidingWriteIntervalSeconds");
         if (dataRefresh)
             assertPositiveInteger(dataRefresh.ttlSeconds, "session.dataRefresh.ttlSeconds");
+        if (dataRefresh && !dataSchema) {
+            throw new Error("Lambder: session.dataRefresh needs session.dataSchema, the schema session.data has. Data a refresh derives " +
+                "changes shape as the app does, and without the schema a record written before the change is served in its " +
+                "old shape until its refresh comes due; with it, such a record refreshes on its next read.");
+        }
+        if (dataSchema !== undefined && typeof dataSchema?.safeParse !== "function") {
+            throw new Error("Lambder: session.dataSchema is not a zod schema.");
+        }
         this.dataRefresh = dataRefresh ?? null;
+        this.dataSchema = dataSchema ?? null;
         this.crypto = crypto ?? new LambderWebCrypto();
         this.assertCryptoFitsStore(store);
         if (typeof sessionSalt !== "string" || sessionSalt.length === 0) {
@@ -167,6 +182,9 @@ export default class LambderSessionManager {
         // logout.
         if (!sessionKey)
             throw new Error("Lambder: createSession sessionKey is empty. It names the subject the session belongs to and partitions the store, so an empty one writes a record no read accepts.");
+        // Refused for the same reason: data the schema refuses would end the
+        // session on its first read, a sign-out right after the sign-in.
+        const served = this.servedDataOf(data, (issues) => new Error(`Lambder: createSession was given data that does not match session.dataSchema (${issues}).`));
         const sessionKeyHash = await this.sessionKeyHashOf(sessionKey);
         // The sort-key SECRET goes to the client; only its hash becomes the
         // store's range key, so the store never contains a usable token.
@@ -186,7 +204,7 @@ export default class LambderSessionManager {
             dataVersion: 0,
         };
         await this.store.create(session);
-        return { session, sessionToken, csrfToken };
+        return { session: { ...session, data: served }, sessionToken, csrfToken };
     }
     /**
      * Writes new session data onto the record, and nothing else: the expiry
@@ -217,14 +235,17 @@ export default class LambderSessionManager {
     async updateSessionData(session, newData) {
         if (!session)
             throw new Error("Invalid session");
+        // Data the schema refuses would end the session on its next read
+        // (see createSession), so the write that brings it fails instead.
+        const served = this.servedDataOf(newData, (issues) => new Error(`Lambder: updateSessionData was given data that does not match session.dataSchema (${issues}).`));
         const { sessionKeyHash, secretHash } = session;
         if (!this.dataRefresh) {
             const result = await this.store.update(sessionKeyHash, secretHash, { data: newData });
-            return result === "missing" ? null : { ...session, data: newData };
+            return result === "missing" ? null : { ...session, data: served };
         }
         const result = await this.store.update(sessionKeyHash, secretHash, { data: newData }, { dataVersion: session.dataVersion });
         if (result === "updated")
-            return { ...session, data: newData, dataVersion: session.dataVersion + 1 };
+            return { ...session, data: served, dataVersion: session.dataVersion + 1 };
         if (result === "missing")
             return null;
         // The data or its deadline was written in between: a revocation was
@@ -235,7 +256,7 @@ export default class LambderSessionManager {
         const now = Math.floor(Date.now() / 1000);
         if (await this.store.update(sessionKeyHash, secretHash, { data: newData, dataExpiresAt: now }) === "missing")
             return null;
-        return { ...session, data: newData, dataExpiresAt: now };
+        return { ...session, data: served, dataExpiresAt: now };
     }
     /**
      * The record a token names, read and structurally checked, with nothing
@@ -304,10 +325,22 @@ export default class LambderSessionManager {
         const now = Math.floor(Date.now() / 1000);
         const refreshed = {};
         const slid = {};
+        // The record's data checked against the schema (see
+        // LambderSessionDataOptions). Without dataRefresh nothing can rebuild
+        // data that does not match, so the session ends.
+        const read = this.dataSchema ? this.dataSchema.safeParse(session.data) : null;
+        if (read && !read.success && !this.dataRefresh) {
+            await this.deleteSession(session);
+            return null;
+        }
+        // What the request is served: the data as the schema reads it, or,
+        // once a refresh ran, the refresh's.
+        let served = read?.success ? read.data : session.data;
         // Renew session.data once its shelf life has passed (opt-in
-        // dataRefresh). A record created while dataRefresh was off has no
-        // dataExpiresAt, so it renews on its first read.
-        if (this.dataRefresh && (session.dataExpiresAt ?? 0) <= now) {
+        // dataRefresh), or at once when it does not match the schema. A
+        // record created while dataRefresh was off has no dataExpiresAt, so
+        // it renews on its first read.
+        if (this.dataRefresh && (read?.success === false || (session.dataExpiresAt ?? 0) <= now)) {
             let newData;
             try {
                 newData = await this.dataRefresh.refresh(session);
@@ -321,6 +354,7 @@ export default class LambderSessionManager {
                 await this.deleteSession(session);
                 return null;
             }
+            served = this.servedDataOf(newData, refreshRefused);
             refreshed.data = newData;
             refreshed.dataExpiresAt = now + this.dataRefresh.ttlSeconds;
         }
@@ -335,7 +369,7 @@ export default class LambderSessionManager {
                 slid.expiresAt = now + session.ttlInSeconds;
             }
         }
-        const renewed = { ...session, ...refreshed, ...slid };
+        const renewed = { ...session, ...refreshed, ...slid, data: served };
         if (refreshed.data === undefined && slid.expiresAt === undefined)
             return renewed;
         // Awaited, so it persists before Lambda freezes. A failing write is
@@ -361,11 +395,27 @@ export default class LambderSessionManager {
         }
         catch (err) {
             console.error(`Lambder session: the renewal write failed, so this session keeps its stored expiry. ${coerceToError(err).message}`);
-            return { ...session, ...refreshed };
+            return { ...session, ...refreshed, data: served };
         }
         return renewed;
     }
     ;
+    /**
+     * Data about to be stored, held to the schema: what a read of it will
+     * serve, or the error `refused` builds from where it does not match.
+     * Data the schema refuses is the app breaking its own declaration, and
+     * storing it would only move the failure to the next read, far from the
+     * code that wrote it. The data is stored as given, not as the schema's
+     * output, so every later read parses exactly what this check accepted.
+     */
+    servedDataOf(data, refused) {
+        if (!this.dataSchema)
+            return data;
+        const checked = this.dataSchema.safeParse(data);
+        if (checked.success)
+            return checked.data;
+        throw refused(describeSchemaIssues(checked.error));
+    }
     /**
      * Runs the dataRefresh callback immediately, regardless of
      * dataExpiresAt, and persists the result onto the same record, over the
@@ -390,13 +440,14 @@ export default class LambderSessionManager {
             await this.deleteSession(session);
             return null;
         }
+        const served = this.servedDataOf(newData, refreshRefused);
         const changes = { data: newData, dataExpiresAt: Math.floor(Date.now() / 1000) + this.dataRefresh.ttlSeconds };
         const result = await this.store.update(session.sessionKeyHash, session.secretHash, changes, { dataVersion: session.dataVersion });
         if (result === "missing")
             return null;
         // "stale": served, not written, and the record keeps the version it
         // was read with (see updateSessionData).
-        return { ...session, ...changes, ...(result === "updated" ? { dataVersion: session.dataVersion + 1 } : {}) };
+        return { ...session, ...changes, data: served, ...(result === "updated" ? { dataVersion: session.dataVersion + 1 } : {}) };
     }
     ;
     /**

package/dist/shared/LambderI18n.js

@@ -112,6 +112,38 @@ const interpolate = (text, params) => {
         return text;
     return text.replace(/\{([^{}]+)\}/g, (token, name) => Object.prototype.hasOwnProperty.call(params, name) ? String(params[name]) : token);
 };
+/** The `{name}` tokens a text carries, as interpolate reads them. */
+const placeholdersOf = (text) => new Set([...text.matchAll(/\{([^{}]+)\}/g)].map((match) => match[1]));
+/** A set of placeholders as a message shows it: `{count}, {name}`, or "none". */
+const describePlaceholders = (placeholders) => placeholders.size ? [...placeholders].sort().map((name) => `{${name}}`).join(", ") : "none";
+/** How many mismatched translations an error lists before it only counts the rest. */
+const PLACEHOLDER_MISMATCH_LIMIT = 20;
+/**
+ * Refuses translations that do not carry the placeholders of the text they
+ * translate. The default language's text is the contract the translator's
+ * type takes its parameters from, so a translation that drops one loses the
+ * value a caller passed, and one that adds one shows its `{token}` as it
+ * is. `lookupDefault` answers the default language's text for a key, and a
+ * key it has none for is left to the other checks.
+ */
+const assertPlaceholdersKept = (lookupDefault, lang, dict, label) => {
+    const mismatches = [];
+    for (const [key, text] of Object.entries(dict)) {
+        const original = lookupDefault(key);
+        if (original === undefined || typeof text !== "string")
+            continue;
+        const expected = placeholdersOf(original);
+        const found = placeholdersOf(text);
+        if (expected.size === found.size && [...expected].every((name) => found.has(name)))
+            continue;
+        mismatches.push(`"${key}" has ${describePlaceholders(found)} where the default language has ${describePlaceholders(expected)}`);
+    }
+    if (mismatches.length === 0)
+        return;
+    const listed = mismatches.slice(0, PLACEHOLDER_MISMATCH_LIMIT).map((line) => `  ${line}`);
+    const more = mismatches.length > PLACEHOLDER_MISMATCH_LIMIT ? [`  ... and ${mismatches.length - PLACEHOLDER_MISMATCH_LIMIT} more`] : [];
+    throw new Error([`LambderI18n: in ${label}, these "${lang}" translations carry other placeholders than the default language's text:`, ...listed, ...more].join("\n"));
+};
 const layerLookup = (layer, lang, key) => {
     for (let node = layer; node; node = node.parent) {
         const value = node.dicts[lang]?.[key];
@@ -133,7 +165,12 @@ const assertInlineDefaultBlock = (dict, defaultLanguage, label) => {
         throw new Error(`LambderI18n: ${label} must give the default language "${defaultLanguage}" inline, not as a loader.`);
     }
 };
-const createLayer = (core, sources, parent) => {
+/**
+ * A layer over its parent, from a dictionary set as configured. The inline
+ * blocks' placeholders are checked here, against the default language's
+ * texts the layer reaches; a loader's are checked when it has run.
+ */
+const createLayer = (core, sources, parent, label) => {
     const layer = { dicts: {}, loaders: new Map(), inFlight: new Map(), parent };
     for (const [lang, source] of Object.entries(sources)) {
         if (typeof source === "function")
@@ -141,6 +178,10 @@ const createLayer = (core, sources, parent) => {
         else if (source)
             layer.dicts[lang] = source;
     }
+    for (const [lang, dict] of Object.entries(layer.dicts)) {
+        if (lang !== core.defaultLanguage && dict)
+            assertPlaceholdersKept((key) => layerLookup(layer, core.defaultLanguage, key), lang, dict, label);
+    }
     if (layer.loaders.size > 0)
         core.lazyLayers.add(layer);
     return layer;
@@ -172,6 +213,7 @@ const startLayerLoad = (core, layer, lang, loader) => {
         const dict = dictionaryFromLoaded(loaded, lang);
         if (layer.parent)
             assertNoRedeclaredKeys(layer.parent, core.defaultLanguage, dict, `the "${lang}" loader`);
+        assertPlaceholdersKept((key) => layerLookup(layer, core.defaultLanguage, key), lang, dict, `the "${lang}" loader`);
         // Translations registered while the loader ran override what it brought.
         layer.dicts[lang] = { ...dict, ...layer.dicts[lang] };
     })
@@ -254,11 +296,11 @@ const buildInstance = (core, layer) => {
         },
         extend(dict) {
             validateExtension(dict, core.languageList, "extend() dictionary");
-            return buildInstance(core, createLayer(core, dict, layer));
+            return buildInstance(core, createLayer(core, dict, layer, "extend() dictionary"));
         },
         extendPartial(dict) {
             validateExtension(dict, core.enforced, "extendPartial() dictionary");
-            return buildInstance(core, createLayer(core, dict, layer));
+            return buildInstance(core, createLayer(core, dict, layer, "extendPartial() dictionary"));
         },
         loadLanguage(code) {
             const lang = code ?? core.state.resolve();
@@ -269,6 +311,9 @@ const buildInstance = (core, layer) => {
         registerDictionary(code, dict) {
             if (!core.isCode(code))
                 throw new Error(`LambderI18n: unsupported language code "${code}".`);
+            if (code !== core.defaultLanguage) {
+                assertPlaceholdersKept((key) => layerLookup(layer, core.defaultLanguage, key), code, dict, `registerDictionary("${code}")`);
+            }
             layer.dicts[code] = { ...layer.dicts[code], ...dict };
             core.state.emitChange();
         },
@@ -350,5 +395,5 @@ export const createLambderI18n = (config) => {
         isCode,
         lazyLayers: new Set(),
     };
-    return buildInstance(core, createLayer(core, config.base, null));
+    return buildInstance(core, createLayer(core, config.base, null, "base dictionary"));
 };

package/dist/shared/contracts/LambderRateLimiter.d.ts

@@ -9,8 +9,8 @@
  * dependency-free, so the mock runtime and the browser entry can resolve it.
  */
 /**
- * The fixed windows a policy may cap, smallest first (the evaluation order),
- * with their length. The policy type derives from this table, so the two can
+ * The fixed windows a policy may cap, smallest first (the order a refusal
+ * names the smallest window by), with their length. The policy type derives from this table, so the two can
  * never drift.
  */
 export declare const RATE_LIMIT_WINDOWS: readonly [{

package/dist/shared/contracts/LambderRateLimiter.js

@@ -9,8 +9,8 @@
  * dependency-free, so the mock runtime and the browser entry can resolve it.
  */
 /**
- * The fixed windows a policy may cap, smallest first (the evaluation order),
- * with their length. The policy type derives from this table, so the two can
+ * The fixed windows a policy may cap, smallest first (the order a refusal
+ * names the smallest window by), with their length. The policy type derives from this table, so the two can
  * never drift.
  */
 export const RATE_LIMIT_WINDOWS = [

package/dist/shared/transport/LambderApiTransport.d.ts

@@ -8,6 +8,7 @@ import type { LambderCompressedGzipPayload, LambderCompressedBrotliPayload } fro
  */
 export type LambderApiTransportRequest = {
     apiPath: string;
+    /** The endpoint called, `group.action`: the call goes to `{apiPath}/{group}/{action}` (apiCallPath). */
     apiName: string;
     version?: string;
     /** The caller's signature for this endpoint, out of its LambderApiSignatureMap; absent when it carries no map. */
@@ -90,7 +91,8 @@ export declare const isLambderTransportFailure: (err: unknown) => err is Lambder
 export type LambderApiTransport = (request: LambderApiTransportRequest) => Promise<LambderApiHttpAnswer>;
 /**
  * The fields of the request envelope, in wire order: the one statement of
- * what a call sends, for every sender.
+ * what a call sends, for every sender. The endpoint is not among them: it is
+ * the path the envelope is posted to (apiCallPath).
  *
  * Two senders write it. A transport hands the payload over as a value
  * (buildTransportEnvelope, below); LambderInvokeCaller has already serialized
@@ -101,7 +103,6 @@ export type LambderApiTransport = (request: LambderApiTransportRequest) => Promi
  * the wire would catch.
  */
 export declare const buildEnvelopeFields: (fields: {
-    apiName: string;
     version?: string;
     signature?: string;
     /** The CSRF token, as the envelope names it. */

package/dist/shared/transport/LambderApiTransport.js

@@ -16,7 +16,8 @@ export class LambderTransportFailure extends Error {
 export const isLambderTransportFailure = (err) => err instanceof Error && err.isLambderTransportFailure === true;
 /**
  * The fields of the request envelope, in wire order: the one statement of
- * what a call sends, for every sender.
+ * what a call sends, for every sender. The endpoint is not among them: it is
+ * the path the envelope is posted to (apiCallPath).
  *
  * Two senders write it. A transport hands the payload over as a value
  * (buildTransportEnvelope, below); LambderInvokeCaller has already serialized
@@ -27,7 +28,6 @@ export const isLambderTransportFailure = (err) => err instanceof Error && err.is
  * the wire would catch.
  */
 export const buildEnvelopeFields = (fields) => ({
-    apiName: fields.apiName,
     version: fields.version,
     ...(fields.signature !== undefined ? { signature: fields.signature } : {}),
     token: fields.token,
@@ -42,7 +42,6 @@ export const buildEnvelopeFields = (fields) => ({
  * runtime read one shape.
  */
 export const buildTransportEnvelope = (request) => buildEnvelopeFields({
-    apiName: request.apiName,
     version: request.version,
     signature: request.signature,
     token: request.token,

package/dist/shared/transport/lambderCookieJarTransport.js

@@ -1,5 +1,6 @@
 import { DEFAULT_SESSION_CSRF_COOKIE_KEY } from "../wire/LambderSessionCookieNames.js";
 import { resolveApiPathTarget } from "./LambderApiTransport.js";
+import { apiCallPath } from "../wire/LambderApiNames.js";
 /**
  * Makes any transport carry a cookie jar the way a browser carries its
  * cookies: the jar's cookies ride on every request, the answer's Set-Cookie
@@ -36,7 +37,7 @@ export const lambderCookieJarTransport = (inner, options) => {
         // absolute cross-origin apiPath. siteHost is "" outside a browser, and
         // an empty host would scope every cookie to nothing while claiming to
         // scope it.
-        const target = resolveApiPathTarget(request.apiPath);
+        const target = resolveApiPathTarget(apiCallPath(request.apiPath, request.apiName));
         const cookieScope = {
             host: target.host ?? options.host ?? (request.siteHost || undefined),
             path: target.path,

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

@@ -0,0 +1,10 @@
+import { AsyncLocalStorage } from "async_hooks";
+/** What any layer may ask of the invocation it runs under. */
+export type LambderInvocation = {
+    /** The invocation's own request id (the Lambda context's awsRequestId); null when the context has none. */
+    readonly requestId: string | null;
+};
+/** The async context the server's handler opens once per invocation. */
+export declare const invocationScope: AsyncLocalStorage<LambderInvocation>;
+/** The request id of the invocation the calling code runs under, or null outside one (a script, a test calling a library directly). */
+export declare const currentRequestId: () => string | null;

package/dist/shared/util/LambderInvocationScope.js

@@ -0,0 +1,5 @@
+import { AsyncLocalStorage } from "async_hooks";
+/** The async context the server's handler opens once per invocation. */
+export const invocationScope = new AsyncLocalStorage();
+/** The request id of the invocation the calling code runs under, or null outside one (a script, a test calling a library directly). */
+export const currentRequestId = () => invocationScope.getStore()?.requestId ?? null;

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

@@ -0,0 +1,22 @@
+/**
+ * One map of named declarations, or a list of them. An app made of parts,
+ * each declaring its own guards, rate-limit policies or refusal codes beside
+ * its APIs, hands the list over, and every name in it is declared. A name two
+ * maps declare is refused rather than one quietly replacing the other.
+ */
+export type LambderNamedMapsOption<TMap> = TMap | readonly TMap[];
+/** The one map a named-maps option declares: a list's members intersected, a lone map as it is. */
+export type LambderMergedNamedMaps<T> = T extends readonly [] ? {} : T extends readonly [infer TFirst, ...infer TRest] ? TFirst & LambderMergedNamedMaps<TRest> : T extends readonly (infer TMember)[] ? TMember : T;
+/** The names a list declares in more than one of its maps: never for a lone map, or for a list whose members are not known one by one. */
+type LambderRepeatedNames<T, TSeen extends PropertyKey = never> = T extends readonly [infer TFirst, ...infer TRest] ? (keyof TFirst & TSeen) | LambderRepeatedNames<TRest, TSeen | keyof TFirst> : never;
+/** Intersected onto a list: a name declared in two of its maps is a compile error, and the property name is the message. */
+export type LambderNoRepeatedNames<T> = [LambderRepeatedNames<T>] extends [never] ? unknown : {
+    readonly "lambder: a name is declared in more than one of these maps. Declare each name once.": LambderRepeatedNames<T>;
+};
+/**
+ * A named-maps option as one map: a lone map as it is, a list merged in
+ * order. A name declared in two maps of the list is refused; `what` names a
+ * declaration and `where` the call that took the list, for that error.
+ */
+export declare const mergeNamedMaps: <TMap extends Record<string, unknown>>(option: LambderNamedMapsOption<TMap>, what: "guard" | "rate-limit policy" | "refusal code", where?: string) => TMap;
+export {};

package/dist/shared/util/LambderNamedMaps.js

@@ -0,0 +1,19 @@
+/**
+ * A named-maps option as one map: a lone map as it is, a list merged in
+ * order. A name declared in two maps of the list is refused; `what` names a
+ * declaration and `where` the call that took the list, for that error.
+ */
+export const mergeNamedMaps = (option, what, where = "create()") => {
+    if (!Array.isArray(option))
+        return option;
+    const merged = {};
+    for (const map of option) {
+        for (const [name, declaration] of Object.entries(map)) {
+            if (Object.prototype.hasOwnProperty.call(merged, name)) {
+                throw new Error(`Lambder: the ${what} "${name}" is declared in two of the maps given to ${where}. Declare each name once.`);
+            }
+            merged[name] = declaration;
+        }
+    }
+    return merged;
+};

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

@@ -35,7 +35,7 @@ export type LambderReadonlyDeep<T, TDepth extends unknown[] = []> = TDepth["leng
  * name, of "this one required and the rest optional".
  *
  * An all-optional map is inhabited by `{}`, which would let `guards: {}`
- * satisfy requireSessionApiGuards / requirePublicApiGuards at the type level
+ * satisfy requireApiGuards at the type level
  * while declaring no guard: the option is present, so the required-field
  * check passes, and it normalizes to zero entries, so nothing runs. Requiring
  * the chosen key also rejects `{ theGuard: undefined }`, which an optional

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

@@ -1,12 +1,12 @@
 /**
  * Lambder API Contract System
  *
- * Contracts are built via method chaining and inferred using typeof lambder.ApiContract
+ * Contracts are the endpoint declarations an instance registered, read with typeof lambder.ApiContract
  */
 import type { LambderCrashDetail } from "./LambderCrashDetail.js";
 import type { LambderUncheckedRefusalMessage, LambderPlainRefusalMessage, LambderRefusalMessage } from "./LambderApiRefusal.js";
 import type { LambderApiIdempotencyOption, LambderGuardsOptionValue, LambderRateLimitOptionValue } from "./LambderApiOptionValues.js";
-/** Whether an endpoint runs without a session or requires one (addApi versus addSessionApi). */
+/** Whether an endpoint runs without a session or requires one: "session" exactly when one of its guards needs a session. */
 export type LambderApiMode = "public" | "session";
 /**
  * Base shape for API contracts: what LambderCaller, LambderInvokeCaller and
@@ -15,7 +15,7 @@ export type LambderApiMode = "public" | "session";
 export type LambderApiContractShape = Record<string, {
     input: any;
     output: any;
-    /** "public" (addApi) or "session" (addSessionApi). */
+    /** "public", or "session" when one of its guards needs a session. */
     mode?: LambderApiMode;
     /** Present when the API declares guardInput-mode guards: guard name -> value the client must send via options.guardInputs. */
     guardInputs?: any;
@@ -149,7 +149,7 @@ export type LambderJsonOf<T> = unknown extends T ? T : T extends LambderJsonValu
     [K in keyof TKeyed as K extends string | number ? (string extends K ? K : number extends K ? K : [LambderJsonOf<TKeyed[K]>] extends [never] ? never : K) : never]: LambderJsonOf<TKeyed[K]>;
 } : never : never;
 /**
- * One contract entry as addApi/addSessionApi record it: the payload types,
+ * One contract entry as defineApi records it: the payload types,
  * the mode, and every declarative option exactly as written. Options that
  * were not written are absent rather than undefined, so `keyof` an entry
  * lists only what the endpoint declared.
@@ -180,20 +180,6 @@ export type LambderContractEntry<In, Out, Mode extends LambderApiMode, GuardInpu
 }) & ([Idempotency] extends [never] ? {} : {
     idempotency: Idempotency;
 });
-/**
- * Merges a new entry into the contract during chaining.
- *
- * The contract is therefore an intersection one member deep per endpoint, and
- * every `C[K]` read generically (a typed caller, a mock registry, a test
- * visitor) resolves the property across all of them. That costs nothing
- * worth measuring in a small app and most of a large client's type check,
- * which is what writeApiContract (lambder/build) is for: it writes the
- * contract out as one object type with plain members, for clients to import
- * instead of the server.
- */
-export type LambderMergeContract<Old, Name extends string, Entry> = Old & {
-    [K in Name]: Entry;
-};
 /** 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. */

package/dist/shared/wire/LambderApiContract.js

@@ -1,6 +1,6 @@
 /**
  * Lambder API Contract System
  *
- * Contracts are built via method chaining and inferred using typeof lambder.ApiContract
+ * Contracts are the endpoint declarations an instance registered, read with typeof lambder.ApiContract
  */
 export {};

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

@@ -0,0 +1,31 @@
+/** The groups a contract's endpoint names hold: the part of each before its dot. */
+export type LambderContractGroupsOf<TContract> = keyof TContract extends infer TName ? (TName extends `${infer TGroup}.${string}` ? TGroup : never) : never;
+/** The endpoint names of one group. */
+export type LambderContractNamesInGroup<TContract, TGroup extends string> = Extract<keyof TContract, `${TGroup}.${string}`> & string;
+/** An endpoint name's action: the part after its dot. */
+export type LambderContractActionOf<TName> = TName extends `${string}.${infer TAction}` ? TAction : never;
+/** A call made through a group: the endpoint's name, and the arguments as the call site passed them. */
+type LambderGroupCallRunner = (apiName: string, args: unknown[]) => unknown;
+/**
+ * The caller, answering for each group a contract could name besides its
+ * own members. A member the caller has (a method, a field) is always the
+ * caller's; a name that could be a group (see isGroupName: an identifier no
+ * caller member has) is one; anything else a runtime or a framework asks of
+ * an object (then, toJSON, a symbol, `__v_isRef`) is what the caller itself
+ * answers, so a caller is never mistaken for a promise, a ref or a
+ * serializable record.
+ *
+ * A caller keeps its state in #private fields, which no property name
+ * reaches, so a group may take any name its public members leave free. Such
+ * a field is readable only on the caller itself, never through this proxy,
+ * so a member is read and a method run on the caller; a method that returns
+ * the caller (setTransport) hands back the proxy, groups and all.
+ *
+ * A group answers the same way one level down: an ordinary object's own
+ * members (toString, valueOf, hasOwnProperty) are an ordinary object's, so
+ * converting a group to a string or asking it what it holds calls no
+ * endpoint; any other name that could be an action (see isActionName) is
+ * one. A group is read-only, like the type that describes it.
+ */
+export declare const withApiGroupCalls: <TCaller extends object>(caller: TCaller, call: LambderGroupCallRunner, outcome: LambderGroupCallRunner) => TCaller;
+export {};