lambder 7.2.1 → 7.2.3

package/CHANGELOG.md

@@ -9,6 +9,50 @@ sit on its first published patch, and later patches list only what they changed.
 Releases up to 3.2.6 carry git tags; the ones after it were published without
 one, so versions are not cross-linked to tag comparisons here.
 
+## [7.2.3] - 2026-09-19
+
+### Added
+
+- **`extensibleEnum(schema)`**, exported from both entries: marks an enum
+  whose readers tolerate values they were not built with, and the signature
+  digest leaves its values out wherever it is output. A list that grows with
+  the product (roles, permissions, statuses) and rides in a widely returned
+  payload changed the signature of every endpoint returning it, so one new
+  permission reloaded every open tab. With the mark, the list growing or
+  shrinking reloads only the clients of endpoints that take it as input,
+  where its values still count because a removed value is a request the
+  server now refuses. The schema's type and validation are unchanged; the
+  mark is zod metadata, read from zod's shared registry. An unmarked enum
+  digests exactly as before, so upgrading changes no signature.
+
+## [7.2.2] - 2026-09-18
+
+### Added
+
+- **Languages loaded on demand in `createLambderI18n`.** Any language block
+  except the default one, in `base`, `extend` and `extendPartial`, can be a
+  loader instead of the dictionary: a function resolving to the dictionary or
+  to a module whose default export is one, so `tr: () => import("./tr")` is
+  the whole thing and a bundler gives each language its own file. Until now
+  every declared language had to be written inline, so every visitor
+  downloaded every language. A loader is checked against the same contract as
+  an inline block, and a missing key is a compile error that names it. The
+  default block stays inline: it is the contract and the fallback every
+  lookup ends in, and creation refuses a loader there.
+- **`i18n.loadLanguage(code?)`** runs a language's loaders (the active
+  language by default) across every instance sharing the root, and resolves
+  once their dictionaries are merged. Until then `t` falls back per key to
+  the default language, as it does for any missing translation. Concurrent
+  calls share each load, and change listeners fire once per load. A loader
+  that answered never runs again; one that rejected rejects the call and runs
+  again on the next. Creating an extension loads nothing, so one created
+  after its language was loaded awaits its own `loadLanguage()`, which runs
+  only what is still missing. `setLanguage` and `resetLanguage` start the
+  loaders of the language they switch to, and listeners fire again when they
+  land; loading first switches without a flash of the default language.
+  Configs without loaders behave exactly as before. The
+  `LambderI18nDictionaryLoader` type is exported from both entries.
+
 ## [7.2.1] - 2026-09-15
 
 ### Added

package/README.md

@@ -146,7 +146,7 @@ guide that matches what you are building. The full index lives in
 | [Frontend client](./docs/client.md) | `LambderCaller`: typed calls, failure outcomes, timeouts, guard inputs, request compression, transports |
 | [Frontend hosting](./docs/frontend-hosting.md) | File sources, `servePublicFiles`, `serveIndexHtml`, `res.templateFile` |
 | [Templating](./docs/templating.md) | `html`/`xml` tagged templates and `LambderTemplatingEngine` |
-| [Translations](./docs/i18n.md) | `createLambderI18n`: typed keys, extension, detection, runtime dictionaries |
+| [Translations](./docs/i18n.md) | `createLambderI18n`: typed keys, extension, detection, on-demand languages, runtime dictionaries |
 | [The mock runtime](./docs/mock.md) | `LambderMockApp`: the typed contract served from mock handlers over the real pipeline, in the browser and in tests |
 | [DynamoDB tables](./docs/dynamodb-tables.md) | Table shapes, TTL and IAM for sessions, cache, rate limits and idempotency |
 | [Exports reference](./docs/exports.md) | Every name the three entry points export, grouped by purpose |
@@ -159,7 +159,7 @@ framework:
 | Module | Guide | Description |
 | --- | --- | --- |
 | `html` / `xml` tags + `LambderTemplatingEngine` | [Templating](./docs/templating.md) | Type-safe tagged templates and a comment-only HTML template engine (build-pipeline-safe) |
-| `createLambderI18n` | [Translations](./docs/i18n.md) | Typed translations with enforced/optional languages, component-level extension and auto language detection (isomorphic) |
+| `createLambderI18n` | [Translations](./docs/i18n.md) | Typed translations with enforced/optional languages, component-level extension, auto language detection and on-demand language loading (isomorphic) |
 | `LambderDdbCache` | [DynamoDB cache](./docs/ddb-cache.md) | DynamoDB-backed compressed JSON cache with lease-based single-fill and grouped keys (server-only) |
 | `LambderDdbRateLimiter` / `LambderMemoryRateLimiter` | [Rate limiter](./docs/ddb-rate-limiter.md) | Fixed-window rate limiter, atomic per window, in DynamoDB (server-only) or in memory |
 | `LambderDdbIdempotencyStore` / `LambderMemoryIdempotencyStore` | [Idempotency store](./docs/ddb-idempotency.md) | Idempotency records with owner-checked claims, in DynamoDB (compressed replays, server-only) or in memory |

package/dist/api/LambderApiSignature.d.ts

@@ -24,9 +24,11 @@ export type LambderApiSignatureEntry = {
  *
  * The description is hashed as built, descriptions and titles included: a
  * schema is what the server says it is, and a client built against a
- * different one reloads once. What must hold for the digest to mean anything
- * is that a schema is built from static values: one that reads the clock, a
- * random source or the environment at construction digests differently in
- * the generator's process and on the server.
+ * different one reloads once, with one exception the schema declares itself:
+ * the values of an extensibleEnum() in an output (see keepShapeOnly). What
+ * must hold for the digest to mean anything is that a schema is built from
+ * static values: one that reads the clock, a random source or the environment
+ * at construction digests differently in the generator's process and on the
+ * server.
  */
 export declare const apiSignatureOf: (definition: LambderApiDefinition, guards: Record<string, LambderApiGuard<any, any, any>> | undefined) => Promise<string>;

package/dist/api/LambderApiSignature.js

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import { toGuardEntries } from "./LambderApiGuards.js";
-import { API_SIGNATURE_HEX_LENGTH } from "../shared/wire/LambderApiSignature.js";
+import { API_SIGNATURE_HEX_LENGTH, EXTENSIBLE_ENUM_META_KEY } from "../shared/wire/LambderApiSignature.js";
 import { sha256HexOf } from "../shared/util/LambderTextDigest.js";
 /*
  * The digest of an endpoint's client-facing shape, computed once, by the
@@ -30,7 +30,7 @@ const sortKeys = (value) => {
     return sorted;
 };
 /**
- * Two edits to every node zod emits, before it is hashed.
+ * Three edits to every node zod emits, before it is hashed.
  *
  * The `default` keyword goes. Its value is server behaviour, not shape: a
  * client never sends it, and its compiled types do not carry it. And for a
@@ -44,11 +44,24 @@ const sortKeys = (value) => {
  *
  * `required` is sorted. It is a set, and the order fields are declared in is
  * not shape either; left as emitted, reordering two fields forced a reload.
+ *
+ * An enum marked with extensibleEnum() loses its values in an output. Its
+ * clients tolerate a value they do not know, so a response carrying one they
+ * were not built with, or no longer carrying one they were, changes nothing
+ * they can see; the node still says it holds a string. In an input the values
+ * stay, since a value dropped from the list is a request an older client may
+ * still send and the server now refuses. The mark itself goes in both, so
+ * marking an enum changes no input's digest.
  */
-const keepShapeOnly = (node) => {
+const keepShapeOnly = (node, io) => {
     delete node.default;
     if (Array.isArray(node.required))
         node.required.sort();
+    if (node[EXTENSIBLE_ENUM_META_KEY] === true) {
+        delete node[EXTENSIBLE_ENUM_META_KEY];
+        if (io === "output")
+            delete node.enum;
+    }
 };
 /**
  * A schema as JSON Schema, as zod emits it minus what keepShapeOnly removes.
@@ -56,7 +69,7 @@ const keepShapeOnly = (node) => {
  * becomes `{}` rather than throwing, because a digest has to exist for every
  * endpoint; what the digest cannot see is documented with it.
  */
-const jsonSchemaOf = (schema, io) => schema ? z.toJSONSchema(schema, { io, unrepresentable: "any", override: ({ jsonSchema }) => keepShapeOnly(jsonSchema) }) : null;
+const jsonSchemaOf = (schema, io) => schema ? z.toJSONSchema(schema, { io, unrepresentable: "any", override: ({ jsonSchema }) => keepShapeOnly(jsonSchema, io) }) : null;
 const ownGuard = (guards, name) => guards !== undefined && Object.prototype.hasOwnProperty.call(guards, name) ? guards[name] : undefined;
 /**
  * The digest of an endpoint's client-facing shape: its name and mode, its
@@ -69,10 +82,12 @@ const ownGuard = (guards, name) => guards !== undefined && Object.prototype.hasO
  *
  * The description is hashed as built, descriptions and titles included: a
  * schema is what the server says it is, and a client built against a
- * different one reloads once. What must hold for the digest to mean anything
- * is that a schema is built from static values: one that reads the clock, a
- * random source or the environment at construction digests differently in
- * the generator's process and on the server.
+ * different one reloads once, with one exception the schema declares itself:
+ * the values of an extensibleEnum() in an output (see keepShapeOnly). What
+ * must hold for the digest to mean anything is that a schema is built from
+ * static values: one that reads the clock, a random source or the environment
+ * at construction digests differently in the generator's process and on the
+ * server.
  */
 export const apiSignatureOf = async (definition, guards) => {
     const guardShapes = toGuardEntries(definition.guards).map(({ name }) => {

package/dist/client.d.ts

@@ -15,7 +15,7 @@ export type { LambderApiTransport, LambderApiTransportRequest, LambderTransportF
 export { LambderCookieJar, parseSetCookie } from "./shared/transport/LambderCookieJar.js";
 export type { LambderStoredCookie } from "./shared/transport/LambderCookieJar.js";
 export { resolveApiOutcome } from "./shared/wire/LambderApiOutcome.js";
-export { apiNameKeyOf, lookupApiSignature, readApiSignature, API_SIGNATURE_HEX_LENGTH } from "./shared/wire/LambderApiSignature.js";
+export { apiNameKeyOf, lookupApiSignature, readApiSignature, API_SIGNATURE_HEX_LENGTH, extensibleEnum } from "./shared/wire/LambderApiSignature.js";
 export type { LambderApiSignatureMap } from "./shared/wire/LambderApiSignature.js";
 export { RELOAD_LOOP_WINDOW_MS } from "./client/LambderReloadLoopBreaker.js";
 export { compareDottedVersions, isDottedVersion } from "./shared/wire/LambderVersionOrder.js";
@@ -32,5 +32,5 @@ export { resolveCompressionOption } from "./shared/wire/LambderCompressionOption
 export type { LambderCompressionOption, LambderCompressionSettingsBase } from "./shared/wire/LambderCompressionOption.js";
 export { html, xml, raw, jsonScript, escapeHtml, renderHtmlValue, LambderSafeHtml, type LambderHtmlValue } from "./shared/LambderHtml.js";
 export { createLambderI18n } from "./shared/LambderI18n.js";
-export type { LambderLanguageMeta, LambderI18nConfig, LambderI18nInstance, LambderI18nTranslator, LambderI18nExtractParams, LambderI18nCodes, LambderI18nKeys, LambderI18nTranslatorFor, } from "./shared/LambderI18n.js";
+export type { LambderLanguageMeta, LambderI18nConfig, LambderI18nInstance, LambderI18nTranslator, LambderI18nExtractParams, LambderI18nDictionaryLoader, LambderI18nCodes, LambderI18nKeys, LambderI18nTranslatorFor, } from "./shared/LambderI18n.js";
 export type { LambderHttpStatusCode } from "./shared/wire/LambderHttpStatus.js";

package/dist/client.js

@@ -14,8 +14,9 @@ export { buildTransportEnvelope, LambderTransportFailure, isLambderTransportFail
 export { lambderCookieJarTransport } from "./shared/transport/lambderCookieJarTransport.js";
 export { LambderCookieJar, parseSetCookie } from "./shared/transport/LambderCookieJar.js";
 export { resolveApiOutcome } from "./shared/wire/LambderApiOutcome.js";
-// The per-endpoint signature map a build ships with, how a caller reads it, and the reload-loop window.
-export { apiNameKeyOf, lookupApiSignature, readApiSignature, API_SIGNATURE_HEX_LENGTH } from "./shared/wire/LambderApiSignature.js";
+// The per-endpoint signature map a build ships with, how a caller reads it, the
+// mark a shared schema sets on an enum its readers let grow, and the reload-loop window.
+export { apiNameKeyOf, lookupApiSignature, readApiSignature, API_SIGNATURE_HEX_LENGTH, extensibleEnum } from "./shared/wire/LambderApiSignature.js";
 export { RELOAD_LOOP_WINDOW_MS } from "./client/LambderReloadLoopBreaker.js";
 export { compareDottedVersions, isDottedVersion } from "./shared/wire/LambderVersionOrder.js";
 // Typed API refusals (isomorphic: shared code may throw them from anywhere;

package/dist/index.d.ts

@@ -27,7 +27,7 @@ export type { LambderApiCallContext, LambderApiCallTrace } from "./api/LambderAp
 export type { LambderApiDefinition } from "./api/LambderApiDefinition.js";
 export { apiSignatureOf } from "./api/LambderApiSignature.js";
 export type { LambderApiSignatureEntry } from "./api/LambderApiSignature.js";
-export { apiNameKeyOf, lookupApiSignature, readApiSignature, API_SIGNATURE_HEX_LENGTH } from "./shared/wire/LambderApiSignature.js";
+export { apiNameKeyOf, lookupApiSignature, readApiSignature, API_SIGNATURE_HEX_LENGTH, extensibleEnum } from "./shared/wire/LambderApiSignature.js";
 export type { LambderApiSignatureMap } from "./shared/wire/LambderApiSignature.js";
 export { RELOAD_LOOP_WINDOW_MS } from "./client/LambderReloadLoopBreaker.js";
 export { compareDottedVersions, isDottedVersion } from "./shared/wire/LambderVersionOrder.js";
@@ -103,7 +103,7 @@ export type { LambderRateLimitKeyFn, LambderRateLimitPer, LambderRateLimitBudget
 export type { LambderApiIdempotencyConfig } from "./api/LambderApiIdempotency.js";
 export type { LambderGuardsOptionValue, LambderRateLimitOverride, LambderRateLimitOptionValue, LambderApiIdempotencyOption, } from "./shared/wire/LambderApiOptionValues.js";
 export { createLambderI18n } from "./shared/LambderI18n.js";
-export type { LambderLanguageMeta, LambderI18nConfig, LambderI18nInstance, LambderI18nTranslator, LambderI18nExtractParams, LambderI18nCodes, LambderI18nKeys, LambderI18nTranslatorFor, } from "./shared/LambderI18n.js";
+export type { LambderLanguageMeta, LambderI18nConfig, LambderI18nInstance, LambderI18nTranslator, LambderI18nExtractParams, LambderI18nDictionaryLoader, LambderI18nCodes, LambderI18nKeys, LambderI18nTranslatorFor, } from "./shared/LambderI18n.js";
 export type { LambderApiContractShape, LambderApiMode, LambderApiEnvelopeBody, LambderApiResponseConfig, LambderApiNullAnswerConfig, LambderContractEntry, LambderMergeContract, LambderGuardNamesIn, LambderContractMode, LambderContractKeysWithMode, LambderContractGuardsOf, LambderContractGuardNames, LambderContractGuardInputsOf, LambderContractGuardInput, LambderContractGuardInputNames, LambderContractRateLimitOf, LambderContractIdempotencyOf, } from "./shared/wire/LambderApiContract.js";
 export type { LambderRenderContext, LambderSessionRenderContext, LambderHttpEvent, LambderHttpEventFormat } from "./core/LambderContext.js";
 export type { LambderApiAnswerOutcome, LambderApiSuccessOutcome, LambderApiCallFailure, LambderApiValidationFailure, LambderApiEnvelopeFailure, LambderApiHttpAnswer, } from "./shared/wire/LambderApiOutcome.js";

package/dist/index.js

@@ -18,7 +18,7 @@ export { LambderAnswerHeaders, getAnswerHeader, setAnswerHeader, addAnswerHeader
 export { createApiCallContext } from "./api/LambderApiCallContext.js";
 // Per-endpoint signatures: what a client build ships with, digested from the server's own registrations.
 export { apiSignatureOf } from "./api/LambderApiSignature.js";
-export { apiNameKeyOf, lookupApiSignature, readApiSignature, API_SIGNATURE_HEX_LENGTH } from "./shared/wire/LambderApiSignature.js";
+export { apiNameKeyOf, lookupApiSignature, readApiSignature, API_SIGNATURE_HEX_LENGTH, extensibleEnum } from "./shared/wire/LambderApiSignature.js";
 export { RELOAD_LOOP_WINDOW_MS } from "./client/LambderReloadLoopBreaker.js";
 export { compareDottedVersions, isDottedVersion } from "./shared/wire/LambderVersionOrder.js";
 export { buildApiEnvelope, envelopeAnswer, refusalAnswer, validationAnswer, apiNotFoundAnswer, sessionExpiredAnswer, versionExpiredAnswer, invalidPayloadAnswer, crashAnswer, API_ANSWER_CONTENT_TYPE, } from "./api/LambderApiEnvelope.js";

package/dist/shared/LambderI18n.d.ts

@@ -25,6 +25,21 @@ export type LambderI18nExtractParams<S extends string> = S extends `${string}{${
  * `{tokens}`, a params object with exactly those tokens is required.
  */
 export type LambderI18nTranslator<TContract extends Record<string, string>> = <K extends keyof TContract & string>(...args: LambderI18nExtractParams<TContract[K]> extends never ? [key: K] : [key: K, params: Record<LambderI18nExtractParams<TContract[K]>, string | number>]) => string;
+/**
+ * A language block fetched on demand instead of bundled: a function that
+ * resolves to the dictionary, or to a module whose default export is the
+ * dictionary, so `() => import("./tr")` is a loader. It runs when
+ * `loadLanguage` asks for its language, never before.
+ */
+export type LambderI18nDictionaryLoader<TDict> = () => Promise<TDict | {
+    default: TDict;
+}>;
+/**
+ * What a non-default language block is checked against: a loader when one was
+ * given, the dictionary otherwise. Checking against the matching side alone,
+ * rather than the union, is what lets a compile error name the missing key.
+ */
+type LanguageBlockFor<TBlocks, L, TDict> = L extends keyof TBlocks ? TBlocks[L] extends (...args: never[]) => unknown ? LambderI18nDictionaryLoader<TDict> : TDict : TDict;
 export interface LambderI18nConfig<TLanguages extends Record<string, LambderLanguageMeta>, TDefault extends keyof TLanguages & string, TEnforced extends readonly (keyof TLanguages & string)[], TBase extends Record<TDefault, Record<string, string>>> {
     /** Master registry of every supported language and its metadata. */
     languages: TLanguages;
@@ -38,9 +53,12 @@ export interface LambderI18nConfig<TLanguages extends Record<string, LambderLang
     /**
      * App-wide base dictionary. Strict: every language in `languages` must
      * provide every key (the `defaultLanguage` block is the typed contract).
+     * Any language but the default may be a loader instead
+     * (`tr: () => import("./tr")`), fetched by `loadLanguage`. The default
+     * block stays inline, because every lookup falls back to it.
      */
     base: TBase & {
-        [L in keyof TLanguages]: Record<keyof TBase[TDefault], string>;
+        [L in keyof TLanguages]: L extends TDefault ? Record<keyof TBase[TDefault], string> : LanguageBlockFor<TBase, L, Record<keyof TBase[TDefault], string>>;
     };
     /**
      * Optional language detector, tried before browser detection. Return a
@@ -61,12 +79,13 @@ export interface LambderI18nInstance<TLanguages extends Record<string, LambderLa
     /**
      * Strict extension: every language must provide every new key. Keys must
      * be new: redeclaring a parent key is a compile-time and runtime error.
+     * Any language but the default may be a loader, as in `base`.
      * Returns a new instance whose key space = parent keys + new keys.
      */
     extend<const TExt extends {
         [D in TDefault]: Record<string, string>;
     }>(dict: {
-        [L in keyof TLanguages]: Record<keyof TExt[TDefault], string>;
+        [L in keyof TLanguages]: L extends TDefault ? Record<keyof TExt[TDefault], string> : LanguageBlockFor<TExt, L, Record<keyof TExt[TDefault], string>>;
     } & {
         [D in TDefault]: Partial<Record<keyof TContract, never>>;
     } & TExt): LambderI18nInstance<TLanguages, TDefault, TEnforced, TContract & TExt[TDefault]>;
@@ -75,19 +94,39 @@ export interface LambderI18nInstance<TLanguages extends Record<string, LambderLa
      * languages are optional (and may provide a subset of keys), and missing
      * translations fall back to the default language. Keys must be new:
      * redeclaring a parent key is a compile-time and runtime error.
+     * Any language but the default may be a loader, as in `base`.
      */
     extendPartial<const TExt extends {
         [D in TDefault]: Record<string, string>;
     }>(dict: {
-        [E in TEnforced[number]]: Record<keyof TExt[TDefault], string>;
+        [E in TEnforced[number]]: E extends TDefault ? Record<keyof TExt[TDefault], string> : LanguageBlockFor<TExt, E, Record<keyof TExt[TDefault], string>>;
     } & {
-        [L in Exclude<keyof TLanguages & string, TEnforced[number]>]?: Partial<Record<keyof TExt[TDefault], string>>;
+        [L in Exclude<keyof TLanguages & string, TEnforced[number]>]?: LanguageBlockFor<TExt, L, Partial<Record<keyof TExt[TDefault], string>>>;
     } & {
         [D in TDefault]: Partial<Record<keyof TContract, never>>;
     } & TExt): LambderI18nInstance<TLanguages, TDefault, TEnforced, TContract & TExt[TDefault]>;
+    /**
+     * Run the loaders a language has in this instance and in every instance
+     * sharing its root, and resolve once their dictionaries are merged.
+     * Defaults to the active language; resolves at once when nothing is left
+     * to load. Until then `t` falls back per key to the default language, so
+     * await it before the first render, and before `setLanguage` to switch
+     * without a flash of the default language. Change listeners fire once
+     * per load, however many calls share it. A loader that answered never
+     * runs again; one that rejected rejects this call and runs again on the
+     * next. Creating an extension loads nothing: one created after its
+     * language was loaded awaits its own `loadLanguage()`, which runs only
+     * what is still missing.
+     */
+    loadLanguage(code?: keyof TLanguages & string): Promise<void>;
     /** Merge additional translations at runtime (e.g. fetched from an API). Notifies change listeners. */
     registerDictionary(code: keyof TLanguages & string, dict: Record<string, string>): void;
-    /** Override the active language (shared with all extended instances). */
+    /**
+     * Override the active language (shared with all extended instances), and
+     * start its loaders; change listeners fire again when they land. Await
+     * `loadLanguage(code)` first to switch without a flash of the default
+     * language.
+     */
     setLanguage(code: keyof TLanguages & string): void;
     /** Clear the override and re-run detection. */
     resetLanguage(): void;
@@ -136,3 +175,4 @@ export type LambderI18nTranslatorFor<T extends {
     t: unknown;
 }> = T["t"];
 export declare const createLambderI18n: <const TLanguages extends Record<string, LambderLanguageMeta>, const TDefault extends keyof TLanguages & string, const TEnforced extends readonly (keyof TLanguages & string)[], const TBase extends Record<TDefault, Record<string, string>>>(config: LambderI18nConfig<TLanguages, TDefault, TEnforced, TBase>) => LambderI18nInstance<TLanguages, TDefault, TEnforced, TBase[TDefault]>;
+export {};

package/dist/shared/LambderI18n.js

@@ -108,6 +108,93 @@ const layerLookup = (layer, lang, key) => {
     }
     return undefined;
 };
+const assertNoRedeclaredKeys = (parent, defaultLanguage, block, label) => {
+    for (const key of Object.keys(block)) {
+        if (layerLookup(parent, defaultLanguage, key) !== undefined) {
+            throw new Error(`LambderI18n: ${label} redeclares existing key "${key}".`);
+        }
+    }
+};
+/** The default block is what every lookup falls back to, so it cannot wait for a loader. */
+const assertInlineDefaultBlock = (dict, defaultLanguage, label) => {
+    if (typeof dict[defaultLanguage] === "function") {
+        throw new Error(`LambderI18n: ${label} must give the default language "${defaultLanguage}" inline, not as a loader.`);
+    }
+};
+const createLayer = (core, sources, parent) => {
+    const layer = { dicts: {}, loaders: new Map(), inFlight: new Map(), parent };
+    for (const [lang, source] of Object.entries(sources)) {
+        if (typeof source === "function")
+            layer.loaders.set(lang, source);
+        else if (source)
+            layer.dicts[lang] = source;
+    }
+    if (layer.loaders.size > 0)
+        core.lazyLayers.add(layer);
+    return layer;
+};
+const isObjectValue = (value) => typeof value === "object" && value !== null;
+/**
+ * A loader resolves to the dictionary itself or to a module whose default
+ * export is the dictionary. The two cannot be confused: a dictionary's values
+ * are strings, so a `default` holding an object can only be a module's.
+ */
+const dictionaryFromLoaded = (loaded, lang) => {
+    const dict = isObjectValue(loaded) && isObjectValue(loaded.default) ? loaded.default : loaded;
+    if (!isObjectValue(dict)) {
+        throw new Error(`LambderI18n: the "${lang}" loader resolved to neither a dictionary nor a module whose default export is one.`);
+    }
+    return dict;
+};
+/** Run a layer's loader for a language and merge what it brings, registered as the layer's load under way. */
+const startLayerLoad = (core, layer, lang, loader) => {
+    const load = Promise.resolve()
+        .then(loader)
+        .then((loaded) => {
+        // A loader that answered is spent even when its answer is refused:
+        // running it again would fetch the same file and fail the same
+        // way. Only a loader that rejected stays, to be retried.
+        layer.loaders.delete(lang);
+        if (layer.loaders.size === 0)
+            core.lazyLayers.delete(layer);
+        const dict = dictionaryFromLoaded(loaded, lang);
+        if (layer.parent)
+            assertNoRedeclaredKeys(layer.parent, core.defaultLanguage, dict, `the "${lang}" loader`);
+        // Translations registered while the loader ran override what it brought.
+        layer.dicts[lang] = { ...dict, ...layer.dicts[lang] };
+    })
+        .finally(() => { layer.inFlight.delete(lang); });
+    layer.inFlight.set(lang, load);
+    return load;
+};
+/**
+ * loadLanguage for a whole root: every layer still holding a loader for the
+ * language. Concurrent calls share each layer's load, and only the call that
+ * started loads announces them, so one load is one change event.
+ */
+const loadLanguageAcrossRoot = async (core, lang) => {
+    const started = [];
+    const joined = [];
+    for (const layer of core.lazyLayers) {
+        const loader = layer.loaders.get(lang);
+        if (!loader)
+            continue;
+        const running = layer.inFlight.get(lang);
+        if (running)
+            joined.push(running);
+        else
+            started.push(startLayerLoad(core, layer, lang, loader));
+    }
+    if (started.length === 0 && joined.length === 0)
+        return;
+    const [startedResults, joinedResults] = await Promise.all([Promise.allSettled(started), Promise.allSettled(joined)]);
+    if (startedResults.some((result) => result.status === "fulfilled"))
+        core.state.emitChange();
+    const failure = [...startedResults, ...joinedResults]
+        .find((result) => result.status === "rejected");
+    if (failure)
+        throw failure.reason;
+};
 const buildInstance = (core, layer) => {
     const translateIn = (lang, key, params) => {
         const text = layerLookup(layer, lang, key)
@@ -127,14 +214,20 @@ const buildInstance = (core, layer) => {
             if (!dict[lang])
                 throw new Error(`LambderI18n: ${label} is missing required language "${lang}".`);
         }
+        assertInlineDefaultBlock(dict, core.defaultLanguage, label);
+        // A loader's keys are checked the same way once it has run.
         for (const block of Object.values(dict)) {
-            for (const key of Object.keys(block ?? {})) {
-                if (layerLookup(layer, core.defaultLanguage, key) !== undefined) {
-                    throw new Error(`LambderI18n: ${label} redeclares existing key "${key}".`);
-                }
-            }
+            if (isObjectValue(block))
+                assertNoRedeclaredKeys(layer, core.defaultLanguage, block, label);
         }
     };
+    // setLanguage and resetLanguage cannot hand a failure back, so it is logged
+    // and the language keeps falling back to the default one.
+    const loadSwitchedLanguage = (lang) => {
+        loadLanguageAcrossRoot(core, lang).catch((err) => {
+            console.error(`LambderI18n: loading "${lang}" after switching to it failed; it falls back to the default language.`, err);
+        });
+    };
     const instance = {
         t,
         forLanguage(code) {
@@ -149,11 +242,17 @@ const buildInstance = (core, layer) => {
         },
         extend(dict) {
             validateExtension(dict, core.languageList, "extend() dictionary");
-            return buildInstance(core, { dicts: { ...dict }, parent: layer });
+            return buildInstance(core, createLayer(core, dict, layer));
         },
         extendPartial(dict) {
             validateExtension(dict, core.enforced, "extendPartial() dictionary");
-            return buildInstance(core, { dicts: { ...dict }, parent: layer });
+            return buildInstance(core, createLayer(core, dict, layer));
+        },
+        loadLanguage(code) {
+            const lang = code ?? core.state.resolve();
+            if (!core.isCode(lang))
+                return Promise.reject(new Error(`LambderI18n: unsupported language code "${lang}".`));
+            return loadLanguageAcrossRoot(core, lang);
         },
         registerDictionary(code, dict) {
             if (!core.isCode(code))
@@ -161,8 +260,14 @@ const buildInstance = (core, layer) => {
             layer.dicts[code] = { ...layer.dicts[code], ...dict };
             core.state.emitChange();
         },
-        setLanguage(code) { core.state.set(code); },
-        resetLanguage() { core.state.reset(); },
+        setLanguage(code) {
+            core.state.set(code);
+            loadSwitchedLanguage(code);
+        },
+        resetLanguage() {
+            core.state.reset();
+            loadSwitchedLanguage(core.state.resolve());
+        },
         get currentLanguage() { return core.state.resolve(); },
         get currentLanguageMeta() { return core.metaByCode.get(core.state.resolve()); },
         get currentDir() {
@@ -213,6 +318,7 @@ export const createLambderI18n = (config) => {
             throw new Error(`LambderI18n: base dictionary contains unsupported language "${lang}".`);
         }
     }
+    assertInlineDefaultBlock(config.base, config.defaultLanguage, "base dictionary");
     const customDetect = config.detectLanguage
         ? () => config.detectLanguage({
             isLanguageCode: isCode,
@@ -230,6 +336,7 @@ export const createLambderI18n = (config) => {
         enforced: config.enforced,
         state: new LanguageState(isCode, config.defaultLanguage, customDetect),
         isCode,
+        lazyLayers: new Set(),
     };
-    return buildInstance(core, { dicts: { ...config.base }, parent: null });
+    return buildInstance(core, createLayer(core, config.base, null));
 };

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

@@ -1,3 +1,4 @@
+import type { z } from "zod";
 /**
  * The per-endpoint signatures a client carries, generated from the server's
  * own registrations (Lambder.apiSignatures()) and shipped with the client
@@ -44,3 +45,39 @@ export declare const lookupApiSignature: (signatures: LambderApiSignatureMap, ap
  * run instead of saying so.
  */
 export declare const readApiSignature: (signatures: LambderApiSignatureMap, apiName: string) => Promise<string>;
+/**
+ * The metadata key extensibleEnum() sets and the digest reads. Namespaced,
+ * because zod writes metadata into the JSON Schema it emits, so the key shows
+ * up in any schema an app converts for itself, where OpenAPI's own
+ * `x-extensible-enum` means something else (the values, in place of `enum`).
+ */
+export declare const EXTENSIBLE_ENUM_META_KEY = "x-lambder-extensible-enum";
+/**
+ * Marks an enum whose clients tolerate a value they were not built with, so
+ * its list of values stays out of the signature of every endpoint that
+ * returns it. Adding a role, a status or a locale to a list that rides in a
+ * widely returned payload (a session, a profile) then reloads only the
+ * clients that send the list back, not every client that reads it.
+ *
+ * Where the enum is input its values still count: a value dropped from the
+ * list is a request an older client may still send and the server now
+ * refuses, so that endpoint's clients must reload. Everything else about the
+ * schema is untouched: its type, its validation on both sides, and what it
+ * is everywhere outside the digest.
+ *
+ * The mark is a promise the schema makes for its readers, and nothing checks
+ * it. A client that switches over every value with no fallback, or indexes a
+ * map by one, renders a value it does not know as nothing, or throws. Mark
+ * only a list every reader handles that way on purpose.
+ *
+ * It is zod metadata (`.meta()`), which zod keeps in one registry on
+ * globalThis, so an enum marked in a shared package is read by the digest
+ * even when the server resolves another copy of zod. A schema derived from a
+ * marked enum by rebuilding it (`z.enum(marked.options)`, `.exclude()`)
+ * carries no mark and counts in full, which costs a reload, never a missed
+ * one.
+ *
+ * @example
+ * export const RoleSchema = extensibleEnum(z.enum(["admin", "member"]));
+ */
+export declare const extensibleEnum: <TSchema extends z.ZodEnum>(schema: TSchema) => TSchema;

package/dist/shared/wire/LambderApiSignature.js

@@ -43,3 +43,39 @@ export const readApiSignature = async (signatures, apiName) => {
     }
     return signature;
 };
+/**
+ * The metadata key extensibleEnum() sets and the digest reads. Namespaced,
+ * because zod writes metadata into the JSON Schema it emits, so the key shows
+ * up in any schema an app converts for itself, where OpenAPI's own
+ * `x-extensible-enum` means something else (the values, in place of `enum`).
+ */
+export const EXTENSIBLE_ENUM_META_KEY = "x-lambder-extensible-enum";
+/**
+ * Marks an enum whose clients tolerate a value they were not built with, so
+ * its list of values stays out of the signature of every endpoint that
+ * returns it. Adding a role, a status or a locale to a list that rides in a
+ * widely returned payload (a session, a profile) then reloads only the
+ * clients that send the list back, not every client that reads it.
+ *
+ * Where the enum is input its values still count: a value dropped from the
+ * list is a request an older client may still send and the server now
+ * refuses, so that endpoint's clients must reload. Everything else about the
+ * schema is untouched: its type, its validation on both sides, and what it
+ * is everywhere outside the digest.
+ *
+ * The mark is a promise the schema makes for its readers, and nothing checks
+ * it. A client that switches over every value with no fallback, or indexes a
+ * map by one, renders a value it does not know as nothing, or throws. Mark
+ * only a list every reader handles that way on purpose.
+ *
+ * It is zod metadata (`.meta()`), which zod keeps in one registry on
+ * globalThis, so an enum marked in a shared package is read by the digest
+ * even when the server resolves another copy of zod. A schema derived from a
+ * marked enum by rebuilding it (`z.enum(marked.options)`, `.exclude()`)
+ * carries no mark and counts in full, which costs a reload, never a missed
+ * one.
+ *
+ * @example
+ * export const RoleSchema = extensibleEnum(z.enum(["admin", "member"]));
+ */
+export const extensibleEnum = (schema) => schema.meta({ [EXTENSIBLE_ENUM_META_KEY]: true });

package/package.json

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