@xndrjs/i18n 0.6.0 → 0.7.0-alpha.0

package/src/IcuTranslationProviderSingle.test.ts

@@ -1,6 +1,5 @@
 import { describe, expect, it } from "vitest";
 import { IcuTranslationProviderSingle } from "./IcuTranslationProviderSingle.js";
-import type { LocaleOfSingle } from "./types.js";
 
 type TestSchema = {
   login_button: { en: string; it: string };
@@ -82,171 +81,62 @@ const dictionary: TestSchema = {
 };
 
 describe("IcuTranslationProviderSingle", () => {
-  const provider = new IcuTranslationProviderSingle<TestSchema, TestParams>(dictionary);
+  const engine = new IcuTranslationProviderSingle<TestSchema, TestParams>(dictionary);
 
-  it("returns a static translation without params", () => {
-    expect(provider.get("login_button", "it")).toBe("Accedi");
-  });
-
-  it("interpolates ICU arguments", () => {
-    expect(provider.get("welcome", "en", { name: "Ada" })).toBe("Welcome Ada!");
-  });
-
-  describe("ICU plural interpolation", () => {
-    it("formats a single numeric plural in English and Italian", () => {
-      expect(provider.get("invoice_count", "en", { count: 1 })).toBe("You have 1 invoice");
-      expect(provider.get("invoice_count", "en", { count: 5 })).toBe("You have 5 invoices");
-      expect(provider.get("invoice_count", "it", { count: 1 })).toBe("Hai 1 fattura");
-      expect(provider.get("invoice_count", "it", { count: 5 })).toBe("Hai 5 fatture");
-    });
-
-    it("uses =5 for an exact match; zero is a locale plural category, not exact match in English", () => {
-      // ICU "zero" is a plural rule category (e.g. Arabic); in English, 0 maps to "other".
-      expect(provider.get("item_count_zero", "en", { count: 0 })).toBe("0 items");
-      // "=5" is an exact-value selector and matches count === 5 in any locale.
-      expect(provider.get("item_count_exact", "en", { count: 0 })).toBe("0 items");
-      expect(provider.get("item_count_exact", "en", { count: 1 })).toBe("1 item");
-      expect(provider.get("item_count_exact", "en", { count: 5 })).toBe("five items");
-    });
+  it("patches a preloaded key and invalidates cache", () => {
+    const local = new IcuTranslationProviderSingle<TestSchema, TestParams>(dictionary);
+    expect(local.toScope().t("login_button", "en")).toBe("Login");
 
-    it("formats nested numeric plurals with double-brace references", () => {
-      expect(provider.get("dashboard_status", "en", { msgCount: 1, chatCount: 1 })).toBe(
-        "You have 1 message in one chat"
-      );
-      expect(provider.get("dashboard_status", "en", { msgCount: 3, chatCount: 2 })).toBe(
-        "You have 3 messages in 2 chats"
-      );
-      expect(provider.get("dashboard_status", "it", { msgCount: 1, chatCount: 1 })).toBe(
-        "Hai 1 messaggio in una chat"
-      );
-      expect(provider.get("dashboard_status", "it", { msgCount: 3, chatCount: 2 })).toBe(
-        "Hai 3 messaggi in 2 chat"
-      );
-    });
+    local.patchKey("login_button", "en", "Sign in");
 
-    it("throws when a required numeric plural parameter is missing", () => {
-      expect(() => provider.get("dashboard_status", "en", { msgCount: 1 } as never)).toThrow(
-        "[i18n Formatting Error]"
-      );
-    });
+    expect(local.toScope().t("login_button", "en")).toBe("Sign in");
+    expect(local.toScope().t("login_button", "it")).toBe("Accedi");
   });
 
-  describe("additional ICU variants", () => {
-    it("formats select arguments as strings", () => {
-      expect(provider.get("inbox_owner", "en", { gender: "female", name: "Ada" })).toBe(
-        "Ada owns her inbox"
-      );
-      expect(provider.get("inbox_owner", "en", { gender: "unknown", name: "Sam" })).toBe(
-        "Sam owns their inbox"
-      );
-    });
-
-    it("formats Italian select with a single other branch and the same params", () => {
-      expect(provider.get("inbox_owner", "it", { gender: "female", name: "Ada" })).toBe(
-        "Ada gestisce la propria casella"
-      );
-      expect(provider.get("inbox_owner", "it", { gender: "male", name: "Luca" })).toBe(
-        "Luca gestisce la propria casella"
-      );
-    });
-
-    it("formats selectordinal arguments as numbers", () => {
-      expect(provider.get("ranking_position", "en", { position: 1 })).toBe("You finished 1st");
-      expect(provider.get("ranking_position", "en", { position: 2 })).toBe("You finished 2nd");
-      expect(provider.get("ranking_position", "en", { position: 3 })).toBe("You finished 3rd");
-      expect(provider.get("ranking_position", "en", { position: 4 })).toBe("You finished 4th");
+  it("merges locales per key with applyLoadMergeSingle without dropping existing locales", () => {
+    const local = new IcuTranslationProviderSingle<TestSchema, TestParams>({
+      ...dictionary,
+      // @ts-expect-error missing locale
+      welcome: {
+        en: "Welcome {name}!",
+      },
     });
 
-    it("formats number, date, and time arguments", () => {
-      const amount = 1234.5;
-      const when = new Date("2026-07-01T13:30:00Z");
-
-      const expectedAmount = new Intl.NumberFormat("en", {
-        style: "currency",
-        currency: "EUR",
-      }).format(amount);
-      const expectedDate = new Intl.DateTimeFormat("en", {
-        dateStyle: "short",
-      }).format(when);
-      const expectedTime = new Intl.DateTimeFormat("en", {
-        timeStyle: "short",
-      }).format(when);
-
-      expect(provider.get("account_balance", "en", { amount })).toBe(`Balance: ${expectedAmount}`);
-      expect(
-        provider.get("appointment_summary", "en", {
-          dueDate: when,
-          startTime: when,
-        })
-      ).toBe(`Due ${expectedDate} at ${expectedTime}`);
+    local.applyLoadMergeSingle({
+      welcome: {
+        // @ts-expect-error adding locale via merge
+        it: "Benvenuto {name}!",
+      },
     });
 
-    it("formats ICU date and number skeletons (::yMMMMd, ::percent)", () => {
-      const when = new Date("2026-07-01T13:30:00Z");
-      const expectedLongDate = new Intl.DateTimeFormat("en", {
-        year: "numeric",
-        month: "long",
-        day: "numeric",
-      }).format(when);
-      const expectedPercent = new Intl.NumberFormat("en", {
-        style: "percent",
-      }).format(0.25);
-
-      expect(provider.get("invoice_due_long", "en", { dueDate: when })).toBe(
-        `Payment due on ${expectedLongDate}`
-      );
-      expect(provider.get("discount_rate", "en", { rate: 0.25 })).toBe(
-        `Save ${expectedPercent} today`
-      );
-    });
+    const view = local.toScope();
+    expect(view.t("welcome", "en", { name: "Ada" })).toBe("Welcome Ada!");
+    expect(view.t("welcome", "it", { name: "Ada" })).toBe("Benvenuto Ada!");
+    expect(view.t("login_button", "en")).toBe("Login");
   });
 
-  it("treats an empty string template as valid", () => {
-    expect(provider.get("empty_label", "en")).toBe("");
-  });
+  it("throws when patching a key that was not preloaded", () => {
+    const local = new IcuTranslationProviderSingle<TestSchema, TestParams>({
+      login_button: { en: "Login" },
+    } as TestSchema);
 
-  it("throws when the key or locale is missing", () => {
-    expect(() =>
-      provider.get("login_button", "fr" as unknown as LocaleOfSingle<TestSchema>)
-    ).toThrow('[i18n] Missing key or locale: "login_button" [fr] (fallback chain: fr)');
-    expect(() => provider.get("missing_key" as "login_button", "en")).toThrow(
-      '[i18n] Missing key or locale: "missing_key" [en] (fallback chain: en)'
+    expect(() => local.patchKey("login_button", "it", "Accedi")).toThrow(
+      "[i18n] Key not preloaded: login_button (it)"
     );
   });
 
-  it("throws on malformed ICU syntax", () => {
-    expect(() => provider.get("broken", "en", { name: "Ada" })).toThrow("[i18n ICU Syntax Error]");
-  });
-
-  it("throws when required parameters are missing", () => {
-    // @ts-expect-error
-    expect(() => provider.get("welcome", "en")).toThrow("[i18n Formatting Error]");
-  });
-
-  it("replaces the dictionary and invalidates cache on setAll", () => {
-    const local = new IcuTranslationProviderSingle<TestSchema, TestParams>(dictionary);
-    expect(local.get("login_button", "en")).toBe("Login");
-
-    local.setAll({
-      ...dictionary,
-      login_button: { en: "Sign in", it: "Entra" },
-    });
-
-    expect(local.get("login_button", "en")).toBe("Sign in");
-  });
-
   it("returns a deep-frozen snapshot from getAll", () => {
-    expect(provider.getAll()).toEqual(dictionary);
-    expect(provider.getAll()).not.toBe(dictionary);
-    expect(Object.isFrozen(provider.getAll())).toBe(true);
+    expect(engine.getAll()).toEqual(dictionary);
+    expect(engine.getAll()).not.toBe(dictionary);
+    expect(Object.isFrozen(engine.getAll())).toBe(true);
   });
 
-  it("does not mutate the provider when getAll snapshot is modified", () => {
-    const snapshot = provider.getAll();
+  it("does not mutate the engine when getAll snapshot is modified", () => {
+    const snapshot = engine.getAll();
     expect(() => {
       snapshot.welcome.en = "Hacked";
     }).toThrow(TypeError);
-    expect(provider.get("welcome", "en", { name: "Ada" })).toBe("Welcome Ada!");
+    expect(engine.toScope().t("welcome", "en", { name: "Ada" })).toBe("Welcome Ada!");
   });
 
   it("does not reflect external dictionary mutations after construction", () => {
@@ -271,91 +161,10 @@ describe("IcuTranslationProviderSingle", () => {
     };
     const local = new IcuTranslationProviderSingle<TestSchema, TestParams>(external);
     external.login_button.en = "Sign in";
-    expect(local.get("login_button", "en")).toBe("Login");
-  });
-
-  describe("forLocale", () => {
-    it("binds a locale so get() no longer requires it", () => {
-      const en = provider.forLocale("en");
-
-      expect(en.locale).toBe("en");
-      expect(en.get("login_button")).toBe("Login");
-      expect(en.get("welcome", { name: "Ada" })).toBe("Welcome Ada!");
-    });
-
-    it("uses the parent provider cache and fallback rules", () => {
-      const fallbackMap = {
-        en: null,
-        "de-CH": "en",
-      } as const;
-      const fallbackProvider = new IcuTranslationProviderSingle<
-        TestSchema,
-        TestParams,
-        keyof typeof fallbackMap | LocaleOfSingle<TestSchema>,
-        typeof fallbackMap
-      >(dictionary, { localeFallback: fallbackMap });
-      const deCh = fallbackProvider.forLocale("de-CH");
-
-      expect(deCh.get("login_button")).toBe("Login");
-    });
+    expect(local.toScope().t("login_button", "en")).toBe("Login");
   });
 
   describe("locale fallback", () => {
-    const fallbackMap = {
-      en: null,
-      "de-DE": "en",
-      "de-CH": "de-DE",
-      it: "en",
-    } as const;
-
-    const fallbackProvider = new IcuTranslationProviderSingle<
-      TestSchema,
-      TestParams,
-      keyof typeof fallbackMap | LocaleOfSingle<TestSchema>,
-      typeof fallbackMap
-    >(dictionary, { localeFallback: fallbackMap });
-
-    it("resolves a locale through the fallback chain", () => {
-      expect(fallbackProvider.get("login_button", "de-CH")).toBe("Login");
-    });
-
-    it("uses an intermediate locale template when available", () => {
-      const withGerman = new IcuTranslationProviderSingle<
-        TestSchema & {
-          login_button: { en: string; it: string; "de-DE": string };
-        },
-        TestParams,
-        keyof typeof fallbackMap | LocaleOfSingle<TestSchema>,
-        typeof fallbackMap
-      >(
-        {
-          ...dictionary,
-          login_button: { en: "Login", it: "Accedi", "de-DE": "Anmelden" },
-        },
-        { localeFallback: fallbackMap }
-      );
-
-      expect(withGerman.get("login_button", "de-CH")).toBe("Anmelden");
-    });
-
-    it("throws when the fallback chain cannot resolve a template", () => {
-      const unresolvedFallback = {
-        en: null,
-        "de-CH": "fr",
-        fr: null,
-      } as const;
-      const unresolvedProvider = new IcuTranslationProviderSingle<
-        TestSchema,
-        TestParams,
-        keyof typeof unresolvedFallback | LocaleOfSingle<TestSchema>,
-        typeof unresolvedFallback
-      >(dictionary, { localeFallback: unresolvedFallback });
-
-      expect(() => unresolvedProvider.get("login_button", "de-CH")).toThrow(
-        '[i18n] Missing key or locale: "login_button" [de-CH] (fallback chain: de-CH → fr)'
-      );
-    });
-
     it("rejects circular fallback maps at construction", () => {
       expect(
         () =>
@@ -365,71 +174,4 @@ describe("IcuTranslationProviderSingle", () => {
       ).toThrow("[i18n] Circular locale fallback detected");
     });
   });
-
-  describe("onMissing", () => {
-    it('throws on missing translations with onMissing: "throw" (explicit default)', () => {
-      const local = new IcuTranslationProviderSingle<TestSchema, TestParams>(dictionary, {
-        onMissing: "throw",
-      });
-      expect(() => local.get("missing_key" as "login_button", "en")).toThrow(
-        '[i18n] Missing key or locale: "missing_key" [en] (fallback chain: en)'
-      );
-    });
-
-    it('returns the key itself with onMissing: "key"', () => {
-      const local = new IcuTranslationProviderSingle<TestSchema, TestParams>(dictionary, {
-        onMissing: "key",
-      });
-      expect(local.get("missing_key" as "login_button", "en")).toBe("missing_key");
-    });
-
-    it("calls a custom handler with the missing-translation context", () => {
-      const contexts: unknown[] = [];
-      const local = new IcuTranslationProviderSingle<TestSchema, TestParams>(dictionary, {
-        onMissing: (context) => {
-          contexts.push(context);
-          return `<missing:${context.key}>`;
-        },
-      });
-
-      expect(local.get("missing_key" as "login_button", "en")).toBe("<missing:missing_key>");
-      expect(contexts).toEqual([{ key: "missing_key", locale: "en", fallbackChain: "en" }]);
-    });
-
-    it("includes the walked fallback chain in the handler context", () => {
-      const fallbackMap = { en: null, "de-CH": "fr", fr: null } as const;
-      const contexts: { fallbackChain: string }[] = [];
-      const local = new IcuTranslationProviderSingle<
-        TestSchema,
-        TestParams,
-        keyof typeof fallbackMap | LocaleOfSingle<TestSchema>,
-        typeof fallbackMap
-      >(dictionary, {
-        localeFallback: fallbackMap,
-        onMissing: (context) => {
-          contexts.push(context);
-          return context.key;
-        },
-      });
-
-      expect(local.get("login_button", "de-CH")).toBe("login_button");
-      expect(contexts[0]?.fallbackChain).toBe("de-CH → fr");
-    });
-
-    it("still throws ICU syntax and formatting errors with a lenient onMissing", () => {
-      const local = new IcuTranslationProviderSingle<TestSchema, TestParams>(dictionary, {
-        onMissing: "key",
-      });
-      expect(() => local.get("broken", "en", { name: "Ada" })).toThrow("[i18n ICU Syntax Error]");
-      // @ts-expect-error
-      expect(() => local.get("welcome", "en")).toThrow("[i18n Formatting Error]");
-    });
-
-    it("applies onMissing through forLocale wrappers", () => {
-      const local = new IcuTranslationProviderSingle<TestSchema, TestParams>(dictionary, {
-        onMissing: "key",
-      });
-      expect(local.forLocale("en").get("missing_key" as "login_button")).toBe("missing_key");
-    });
-  });
 });

package/src/IcuTranslationProviderSingle.ts

@@ -1,5 +1,13 @@
 import { cloneAndFreeze } from "./deep-freeze.js";
+import { BuilderLoadRegistry, SINGLE_BUILDER_RESOURCE } from "./builder-load-registry.js";
+import type { I18nEngineSingle } from "./engine.js";
 import { resolveAndFormat } from "./format-core.js";
+import {
+  assertPatchKeySingle,
+  recordPreloadedKeysSingle,
+  seedPreloadedKeysSingle,
+} from "./patch-key.js";
+import { mergeNamespaceLocalesCore } from "./project-locales.js";
 import { validateLocaleFallback } from "./resolve-locale.js";
 import type {
   IcuTranslationProviderOptions,
@@ -8,76 +16,28 @@ import type {
   LocaleOfSingle,
   OnMissingTranslation,
   SingleCompiledCache,
+  PartialKeyDictionary,
 } from "./types.js";
-
-export interface TranslationProviderSingleForLocale<
-  Schema extends KeyDictionary,
-  Params extends { [K in keyof Schema]: unknown },
-  Locale extends string,
-> {
-  readonly locale: Locale;
-  get<K extends keyof Schema & string>(
-    key: K,
-    ...params: Params[K] extends never ? [] : [params: Params[K]]
-  ): string;
-}
-
-export interface TranslationProviderSingle<
-  Schema extends KeyDictionary,
-  Params extends { [K in keyof Schema]: unknown },
-  RequestLocales extends string = LocaleOfSingle<Schema>,
-> {
-  get<K extends keyof Schema & string>(
-    key: K,
-    locale: RequestLocales,
-    ...params: Params[K] extends never ? [] : [params: Params[K]]
-  ): string;
-  forLocale<Locale extends RequestLocales>(
-    locale: Locale
-  ): TranslationProviderSingleForLocale<Schema, Params, Locale>;
-  getAll(): Schema;
-  setAll(values: Schema): void;
-}
-
-export class IcuTranslationProviderSingleForLocale<
-  Schema extends KeyDictionary,
-  Params extends { [K in keyof Schema]: unknown },
-  RequestLocales extends string,
-  Locale extends RequestLocales,
-  Fallback extends LocaleFallbackMap | undefined,
-> implements TranslationProviderSingleForLocale<Schema, Params, Locale> {
-  constructor(
-    private readonly provider: IcuTranslationProviderSingle<
-      Schema,
-      Params,
-      RequestLocales,
-      Fallback
-    >,
-    readonly locale: Locale
-  ) {}
-
-  get<K extends keyof Schema & string>(
-    key: K,
-    ...args: Params[K] extends never ? [] : [params: Params[K]]
-  ): string {
-    const params = args[0] as Record<string, unknown> | undefined;
-    return this.provider.getWithLocale(String(key), this.locale, params);
-  }
-}
+import { I18nScopeSingleForLocaleImpl, I18nScopeSingleImpl } from "./scope-single.js";
 
 export class IcuTranslationProviderSingle<
   Schema extends KeyDictionary,
   Params extends { [K in keyof Schema]: unknown },
   RequestLocales extends string = LocaleOfSingle<Schema>,
   Fallback extends LocaleFallbackMap | undefined = undefined,
-> implements TranslationProviderSingle<Schema, Params, RequestLocales> {
+> implements I18nEngineSingle<Schema, Params, RequestLocales> {
+  readonly __i18nEngineMode = "single" as const;
+
   private dictionary: Schema;
   private compiledCache: SingleCompiledCache = {};
+  private readonly preloadedKeys = new Set<string>();
+  private readonly builderLoadRegistry = new BuilderLoadRegistry();
   private readonly localeFallback?: Fallback;
   private readonly onMissing: OnMissingTranslation;
 
   constructor(dictionary: Schema, options?: IcuTranslationProviderOptions<Fallback>) {
     this.dictionary = structuredClone(dictionary);
+    seedPreloadedKeysSingle(this.dictionary, this.preloadedKeys);
     if (options?.localeFallback) {
       validateLocaleFallback(options.localeFallback);
       this.localeFallback = options.localeFallback;
@@ -85,15 +45,6 @@ export class IcuTranslationProviderSingle<
     this.onMissing = options?.onMissing ?? "throw";
   }
 
-  get<K extends keyof Schema & string>(
-    key: K,
-    locale: RequestLocales,
-    ...args: Params[K] extends never ? [] : [params: Params[K]]
-  ): string {
-    const params = args[0] as Record<string, unknown> | undefined;
-    return this.getWithLocale(String(key), locale, params);
-  }
-
   getWithLocale(key: string, locale: string, params?: Record<string, unknown>): string {
     return resolveAndFormat({
       localeByKey: this.dictionary[key],
@@ -114,18 +65,50 @@ export class IcuTranslationProviderSingle<
     });
   }
 
-  forLocale<Locale extends RequestLocales>(
-    locale: Locale
-  ): IcuTranslationProviderSingleForLocale<Schema, Params, RequestLocales, Locale, Fallback> {
-    return new IcuTranslationProviderSingleForLocale(this, locale);
+  toScope(): I18nScopeSingleImpl<Schema, Params, RequestLocales, Fallback>;
+  toScope<Locale extends RequestLocales>(options: {
+    locale: Locale;
+  }): I18nScopeSingleForLocaleImpl<Schema, Params, RequestLocales, Locale, Fallback>;
+  toScope<Locale extends RequestLocales>(options?: { locale?: Locale }) {
+    if (options?.locale !== undefined) {
+      return new I18nScopeSingleForLocaleImpl(this, options.locale);
+    }
+    return new I18nScopeSingleImpl(this);
   }
 
   getAll(): Schema {
     return cloneAndFreeze(this.dictionary);
   }
 
-  setAll(values: Schema): void {
-    this.dictionary = structuredClone(values);
-    this.compiledCache = {};
+  hasBuilderResourceLoaded(partition: string | undefined): boolean {
+    return this.builderLoadRegistry.has(SINGLE_BUILDER_RESOURCE, partition);
+  }
+
+  markBuilderResourceLoaded(partition: string | undefined): void {
+    this.builderLoadRegistry.mark(SINGLE_BUILDER_RESOURCE, partition);
+  }
+
+  applyLoadMergeSingle(values: PartialKeyDictionary<Schema, RequestLocales>): void {
+    this.dictionary = mergeNamespaceLocalesCore(this.dictionary, values);
+    recordPreloadedKeysSingle(values, this.preloadedKeys);
+
+    for (const [key, incomingLocales] of Object.entries(values)) {
+      if (incomingLocales === undefined || typeof incomingLocales !== "object") {
+        continue;
+      }
+
+      for (const locale of Object.keys(incomingLocales)) {
+        delete this.compiledCache[locale]?.[key];
+      }
+    }
+  }
+
+  patchKey(key: string, locale: string, template: string): void {
+    assertPatchKeySingle(key, locale, template, this.preloadedKeys, this.dictionary[key]);
+
+    this.dictionary = mergeNamespaceLocalesCore(this.dictionary, {
+      [key]: { [locale]: template },
+    } as PartialKeyDictionary<Schema, RequestLocales>);
+    delete this.compiledCache[locale]?.[key];
   }
 }

package/src/builder-load-registry.ts

@@ -0,0 +1,18 @@
+/** Stable key for a lazy-loaded builder resource (namespace + locale or delivery area). */
+export function formatBuilderResourceKey(namespace: string, partition: string | undefined): string {
+  return `${namespace}\0${partition ?? ""}`;
+}
+
+export const SINGLE_BUILDER_RESOURCE = "__dictionary__";
+
+export class BuilderLoadRegistry {
+  private readonly loaded = new Set<string>();
+
+  has(namespace: string, partition: string | undefined): boolean {
+    return this.loaded.has(formatBuilderResourceKey(namespace, partition));
+  }
+
+  mark(namespace: string, partition: string | undefined): void {
+    this.loaded.add(formatBuilderResourceKey(namespace, partition));
+  }
+}

package/src/builder-loaders.ts

@@ -0,0 +1,18 @@
+/** Canonical lazy loader — no locale or delivery-area partition. */
+export type CanonicalLoader<T> = () => Promise<T> | T;
+
+/** Split-by-locale or custom-area loader — partition key is locale or area name. */
+export type PartitionedLoader<T> = (partition: string) => Promise<T> | T;
+
+export type NamespaceLoader<T> = CanonicalLoader<T> | PartitionedLoader<T>;
+
+export async function invokeNamespaceLoader<T>(
+  loader: NamespaceLoader<T>,
+  partition: string | undefined
+): Promise<T> {
+  if (partition === undefined) {
+    return await (loader as CanonicalLoader<T>)();
+  }
+
+  return await (loader as PartitionedLoader<T>)(partition);
+}