lambder 3.2.2 → 3.2.4

package/dist/LambderI18n.d.ts

@@ -25,7 +25,7 @@ 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;
-export interface LambderI18nConfig<TLanguages extends Record<string, LambderLanguageMeta>, TDefault extends keyof TLanguages & string, TEnforced extends readonly (keyof TLanguages & string)[], TContract extends Record<string, string>> {
+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;
     /** Final fallback language. Must be included in `enforced`. */
@@ -39,10 +39,8 @@ 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).
      */
-    base: {
-        [L in keyof TLanguages]: Record<keyof TContract, string>;
-    } & {
-        [D in TDefault]: TContract;
+    base: TBase & {
+        [L in keyof TLanguages]: Record<keyof TBase[TDefault], string>;
     };
     /**
      * Optional language detector, tried before browser detection. Return a
@@ -61,18 +59,22 @@ export interface LambderI18nInstance<TLanguages extends Record<string, LambderLa
     /** Translator bound to an explicit language (per-request backend use). */
     forLanguage(code: keyof TLanguages & string): LambderI18nTranslator<TContract>;
     /**
-     * Strict extension: every language must provide every new key.
+     * Strict extension: every language must provide every new key. Keys must
+     * be new — redeclaring a parent key is a compile-time and runtime error.
      * 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>;
+    } & {
+        [D in TDefault]: Partial<Record<keyof TContract, never>>;
     } & TExt): LambderI18nInstance<TLanguages, TDefault, TEnforced, TContract & TExt[TDefault]>;
     /**
      * Partial extension: only the `enforced` languages are required; all other
      * languages are optional (and may provide a subset of keys) — missing
-     * translations fall back to the default language.
+     * translations fall back to the default language. Keys must be new —
+     * redeclaring a parent key is a compile-time and runtime error.
      */
     extendPartial<const TExt extends {
         [D in TDefault]: Record<string, string>;
@@ -80,8 +82,10 @@ export interface LambderI18nInstance<TLanguages extends Record<string, LambderLa
         [E in TEnforced[number]]: Record<keyof TExt[TDefault], string>;
     } & {
         [L in Exclude<keyof TLanguages & string, TEnforced[number]>]?: Partial<Record<keyof TExt[TDefault], string>>;
+    } & {
+        [D in TDefault]: Partial<Record<keyof TContract, never>>;
     } & TExt): LambderI18nInstance<TLanguages, TDefault, TEnforced, TContract & TExt[TDefault]>;
-    /** Merge additional translations at runtime (e.g. fetched from an API). */
+    /** 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). */
     setLanguage(code: keyof TLanguages & string): void;
@@ -89,9 +93,18 @@ export interface LambderI18nInstance<TLanguages extends Record<string, LambderLa
     resetLanguage(): void;
     /** The currently active language code. */
     readonly currentLanguage: keyof TLanguages & string;
-    /** Metadata of the currently active language. */
-    readonly currentLanguageMeta: TLanguages[keyof TLanguages];
-    /** Subscribe to language changes. Returns an unsubscribe function. */
+    /** Metadata of the currently active language, with `code` injected. */
+    readonly currentLanguageMeta: TLanguages[keyof TLanguages] & {
+        code: keyof TLanguages & string;
+    };
+    /** Text direction of the active language (defaults to "ltr"). */
+    readonly currentDir: "ltr" | "rtl";
+    /** BCP-47 locale of the active language for Intl APIs (defaults to the code). */
+    readonly currentIntlLocale: string;
+    /**
+     * Subscribe to changes (language switched, or runtime dictionaries
+     * registered). Returns an unsubscribe function.
+     */
     onLanguageChange(listener: (code: keyof TLanguages & string) => void): () => void;
     /**
      * Apply the active language to `<html lang>` and `<html dir>` (RTL support).
@@ -103,7 +116,23 @@ export interface LambderI18nInstance<TLanguages extends Record<string, LambderLa
     isLanguageCode(value: string): value is keyof TLanguages & string;
     readonly languages: TLanguages;
     readonly languageList: (keyof TLanguages & string)[];
+    /** Ordered language metadata (declaration order), with `code` injected — ready for switcher menus. */
+    readonly languageMetaList: (TLanguages[keyof TLanguages] & {
+        code: keyof TLanguages & string;
+    })[];
     readonly defaultLanguage: TDefault;
     readonly enforced: TEnforced;
 }
-export declare const createLambderI18n: <const TLanguages extends Record<string, LambderLanguageMeta>, const TDefault extends keyof TLanguages & string, const TEnforced extends readonly (keyof TLanguages & string)[], const TContract extends Record<string, string>>(config: LambderI18nConfig<TLanguages, TDefault, TEnforced, TContract>) => LambderI18nInstance<TLanguages, TDefault, TEnforced, TContract>;
+/** Language codes of an instance: `LambderI18nCodes<typeof i18n>`. */
+export type LambderI18nCodes<T extends {
+    languageList: readonly string[];
+}> = T["languageList"][number];
+/** Translation keys of an instance: `LambderI18nKeys<typeof i18n>`. */
+export type LambderI18nKeys<T extends {
+    t: (...args: never[]) => string;
+}> = Parameters<T["t"]>[0];
+/** Translator type of an instance: `LambderI18nTranslatorFor<typeof i18n>`. */
+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]>;

package/dist/LambderI18n.js

@@ -42,7 +42,14 @@ class LanguageState {
             return this.override;
         if (this.detected)
             return this.detected;
-        const custom = this.customDetect?.();
+        // Fail-open: a broken app detector must not take down every t() call.
+        let custom = null;
+        try {
+            custom = this.customDetect?.();
+        }
+        catch (err) {
+            console.error("LambderI18n: detectLanguage threw; continuing detection chain.", err);
+        }
         if (custom && this.isCode(custom)) {
             this.detected = custom;
             return custom;
@@ -64,13 +71,24 @@ class LanguageState {
         this.detected = null;
         this.notify(this.resolve());
     }
+    /** Re-notify listeners without a language change (e.g. dictionaries changed). */
+    emitChange() {
+        this.notify(this.resolve());
+    }
     subscribe(listener) {
         this.listeners.add(listener);
         return () => { this.listeners.delete(listener); };
     }
     notify(code) {
-        for (const listener of this.listeners)
-            listener(code);
+        for (const listener of this.listeners) {
+            // Isolate listeners: one bad subscriber must not block the others.
+            try {
+                listener(code);
+            }
+            catch (err) {
+                console.error("LambderI18n: onLanguageChange listener threw.", err);
+            }
+        }
     }
 }
 const interpolate = (text, params) => {
@@ -98,6 +116,8 @@ const buildInstance = (core, layer) => {
         return interpolate(text, params);
     };
     const t = (key, params) => translateIn(core.state.resolve(), key, params);
+    // forLanguage sits on the hot path of reactive T() bridges: cache per code.
+    const translatorCache = new Map();
     const validateExtension = (dict, requiredLanguages, label) => {
         for (const lang of Object.keys(dict)) {
             if (!core.isCode(lang))
@@ -107,31 +127,51 @@ const buildInstance = (core, layer) => {
             if (!dict[lang])
                 throw new Error(`LambderI18n: ${label} is missing required language "${lang}".`);
         }
+        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}".`);
+                }
+            }
+        }
     };
     const instance = {
-        t: t,
+        t,
         forLanguage(code) {
+            const cached = translatorCache.get(code);
+            if (cached)
+                return cached;
             if (!core.isCode(code))
                 throw new Error(`LambderI18n: unsupported language code "${code}".`);
-            return ((key, params) => translateIn(code, key, params));
+            const translator = (key, params) => translateIn(code, key, params);
+            translatorCache.set(code, translator);
+            return translator;
         },
         extend(dict) {
             validateExtension(dict, core.languageList, "extend() dictionary");
-            return buildInstance(core, { dicts: dict, parent: layer });
+            return buildInstance(core, { dicts: { ...dict }, parent: layer });
         },
         extendPartial(dict) {
             validateExtension(dict, core.enforced, "extendPartial() dictionary");
-            return buildInstance(core, { dicts: dict, parent: layer });
+            return buildInstance(core, { dicts: { ...dict }, parent: layer });
         },
         registerDictionary(code, dict) {
             if (!core.isCode(code))
                 throw new Error(`LambderI18n: unsupported language code "${code}".`);
             layer.dicts[code] = { ...layer.dicts[code], ...dict };
+            core.state.emitChange();
         },
         setLanguage(code) { core.state.set(code); },
         resetLanguage() { core.state.reset(); },
         get currentLanguage() { return core.state.resolve(); },
-        get currentLanguageMeta() { return core.languages[core.state.resolve()]; },
+        get currentLanguageMeta() { return core.metaByCode.get(core.state.resolve()); },
+        get currentDir() {
+            return core.metaByCode.get(core.state.resolve())?.dir ?? "ltr";
+        },
+        get currentIntlLocale() {
+            const code = core.state.resolve();
+            return core.metaByCode.get(code)?.intlLocale ?? code;
+        },
         onLanguageChange(listener) { return core.state.subscribe(listener); },
         applyToDocument() {
             const doc = globalThis.document;
@@ -139,11 +179,12 @@ const buildInstance = (core, layer) => {
                 return;
             const code = core.state.resolve();
             doc.documentElement.lang = code;
-            doc.documentElement.dir = core.languages[code]?.dir ?? "ltr";
+            doc.documentElement.dir = core.metaByCode.get(code)?.dir ?? "ltr";
         },
         isLanguageCode: core.isCode,
         languages: core.languages,
         languageList: core.languageList,
+        languageMetaList: core.metaList,
         defaultLanguage: core.defaultLanguage,
         enforced: core.enforced,
     };
@@ -167,6 +208,11 @@ export const createLambderI18n = (config) => {
             throw new Error(`LambderI18n: base dictionary is missing language "${lang}".`);
         }
     }
+    for (const lang of Object.keys(config.base)) {
+        if (!isCode(lang)) {
+            throw new Error(`LambderI18n: base dictionary contains unsupported language "${lang}".`);
+        }
+    }
     const customDetect = config.detectLanguage
         ? () => config.detectLanguage({
             isLanguageCode: isCode,
@@ -174,9 +220,12 @@ export const createLambderI18n = (config) => {
             defaultLanguage: config.defaultLanguage,
         })
         : null;
+    const metaByCode = new Map(languageList.map((code) => [code, { code, ...config.languages[code] }]));
     const core = {
         languages: config.languages,
         languageList,
+        metaByCode,
+        metaList: [...metaByCode.values()],
         defaultLanguage: config.defaultLanguage,
         enforced: config.enforced,
         state: new LanguageState(isCode, config.defaultLanguage, customDetect),

package/dist/index.d.ts

@@ -20,7 +20,7 @@ export type { LambderSessionContext } from "./LambderSessionManager.js";
 export { LambderDdbCache } from "./LambderDdbCache.js";
 export type { LambderDdbCacheOptions, LambderDdbCacheSetOptions, LambderDdbCacheGetOrSetOptions, } from "./LambderDdbCache.js";
 export { createLambderI18n } from "./LambderI18n.js";
-export type { LambderLanguageMeta, LambderI18nConfig, LambderI18nInstance, LambderI18nTranslator, LambderI18nExtractParams, } from "./LambderI18n.js";
+export type { LambderLanguageMeta, LambderI18nConfig, LambderI18nInstance, LambderI18nTranslator, LambderI18nExtractParams, LambderI18nCodes, LambderI18nKeys, LambderI18nTranslatorFor, } from "./LambderI18n.js";
 export { type ApiContractShape, } from "./LambderApiContract.js";
 export type { LambderRenderContext, LambderSessionRenderContext, LambderHttpEvent } from "./LambderContext.js";
 export { createContext, isV2HttpEvent } from "./LambderContext.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lambder",
-  "version": "3.2.2",
+  "version": "3.2.4",
   "description": "",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",