lambder 7.2.1 → 7.2.2

package/CHANGELOG.md

@@ -9,6 +9,34 @@ 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.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/client.d.ts

@@ -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/index.d.ts

@@ -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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lambder",
-  "version": "7.2.1",
+  "version": "7.2.2",
   "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": [