@xndrjs/i18n 0.6.1 → 0.7.0

package/src/IcuTranslationProviderMulti.test.ts

@@ -1,6 +1,5 @@
 import { describe, expect, it } from "vitest";
 import { IcuTranslationProviderMulti } from "./IcuTranslationProviderMulti.js";
-import type { LocaleOfMulti } from "./types.js";
 
 type TestSchema = {
   default: {
@@ -69,199 +68,141 @@ const dictionary: TestSchema = {
 };
 
 describe("IcuTranslationProviderMulti", () => {
-  const provider = new IcuTranslationProviderMulti<TestSchema, TestParams>(dictionary);
+  const engine = new IcuTranslationProviderMulti<TestSchema, TestParams>(dictionary);
 
-  it("resolves translations by namespace and key", () => {
-    expect(provider.get("default", "login_button", "it")).toBe("Accedi");
-    expect(provider.get("default", "welcome", "en", { name: "Ada" })).toBe("Welcome Ada!");
-  });
+  it("tracks namespaces via dictionary keys", () => {
+    const partial = new IcuTranslationProviderMulti<TestSchema, TestParams>({
+      default: dictionary.default,
+    });
 
-  it("formats ICU plurals with multiple parameters", () => {
-    expect(provider.get("billing", "invoice_summary", "en", { count: 1, name: "Ada" })).toBe(
-      "You have 1 invoice for Ada"
-    );
-    expect(provider.get("billing", "invoice_summary", "en", { count: 3, name: "Ada" })).toBe(
-      "You have 3 invoices for Ada"
-    );
-    expect(provider.get("billing", "invoice_summary", "it", { count: 1, name: "Ada" })).toBe(
-      "Hai 1 fattura per Ada"
-    );
-    expect(provider.get("billing", "invoice_summary", "it", { count: 3, name: "Ada" })).toBe(
-      "Hai 3 fatture per Ada"
-    );
+    expect("default" in partial.getAll()).toBe(true);
+    expect("billing" in partial.getAll()).toBe(false);
   });
 
-  it("formats nested numeric plurals with double-brace references", () => {
-    expect(provider.get("default", "dashboard_status", "en", { msgCount: 1, chatCount: 1 })).toBe(
-      "You have 1 message in one chat"
-    );
-    expect(provider.get("default", "dashboard_status", "en", { msgCount: 3, chatCount: 2 })).toBe(
-      "You have 3 messages in 2 chats"
-    );
-    expect(provider.get("default", "dashboard_status", "it", { msgCount: 1, chatCount: 1 })).toBe(
-      "Hai 1 messaggio in una chat"
-    );
-    expect(provider.get("default", "dashboard_status", "it", { msgCount: 3, chatCount: 2 })).toBe(
-      "Hai 3 messaggi in 2 chat"
-    );
-  });
+  it("supports partial initialization", () => {
+    const partial = new IcuTranslationProviderMulti<TestSchema, TestParams>({
+      default: dictionary.default,
+    });
 
-  it("formats select and selectordinal ICU variants", () => {
-    expect(provider.get("default", "inbox_owner", "en", { gender: "male", name: "Linus" })).toBe(
-      "Linus owns his inbox"
-    );
-    expect(provider.get("default", "ranking_position", "en", { position: 3 })).toBe(
-      "You finished 3rd"
+    expect(partial.toScope({ namespaces: ["default"] }).t("default", "login_button", "en")).toBe(
+      "Login"
     );
   });
 
-  it("formats number, date, and time ICU variants", () => {
-    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);
+  it("patches a preloaded key and invalidates its cache", () => {
+    const local = new IcuTranslationProviderMulti<TestSchema, TestParams>(dictionary);
+    const view = () => local.toScope({ namespaces: ["default", "billing"] });
 
-    expect(provider.get("billing", "account_balance", "en", { amount })).toBe(
-      `Balance: ${expectedAmount}`
+    expect(view().t("billing", "invoice_summary", "en", { count: 2, name: "Bob" })).toBe(
+      "You have 2 invoices for Bob"
     );
-    expect(
-      provider.get("billing", "appointment_summary", "en", {
-        dueDate: when,
-        startTime: when,
-      })
-    ).toBe(`Due ${expectedDate} at ${expectedTime}`);
-  });
-
-  it("treats an empty string template as valid", () => {
-    expect(provider.get("billing", "empty_label", "en")).toBe("");
-  });
-
-  it("tracks loaded namespaces with hasNamespace", () => {
-    const partial = new IcuTranslationProviderMulti<TestSchema, TestParams>({
-      default: dictionary.default,
-    });
 
-    expect(partial.hasNamespace("default")).toBe(true);
-    expect(partial.hasNamespace("billing")).toBe(false);
-  });
-
-  it("throws when getting from an unloaded namespace", () => {
-    const partial = new IcuTranslationProviderMulti<TestSchema, TestParams>({
-      default: dictionary.default,
-    });
+    local.patchKeyMulti(
+      "billing",
+      "invoice_summary",
+      "en",
+      "{count, plural, one {1 bill} other {{count} bills}} for {name}"
+    );
 
-    expect(() =>
-      partial.get("billing", "invoice_summary", "en", { count: 1, name: "Ada" })
-    ).toThrow(
-      '[i18n] Namespace not loaded: "billing". Register it with setNamespace() before calling .get().'
+    expect(view().t("billing", "invoice_summary", "en", { count: 2, name: "Bob" })).toBe(
+      "2 bills for Bob"
     );
+    expect(view().t("default", "login_button", "en")).toBe("Login");
   });
 
-  it("supports partial initialization", () => {
+  it("adds namespace to dictionary with applyLoadMergeNamespace", () => {
     const partial = new IcuTranslationProviderMulti<TestSchema, TestParams>({
       default: dictionary.default,
     });
+    expect("billing" in partial.getAll()).toBe(false);
 
-    expect(partial.get("default", "login_button", "en")).toBe("Login");
+    partial.applyLoadMergeNamespace("billing", dictionary.billing);
+    expect("billing" in partial.getAll()).toBe(true);
   });
 
-  it("throws when namespace, key, or locale is missing", () => {
-    expect(() =>
-      provider.get("default", "login_button", "fr" as unknown as LocaleOfMulti<TestSchema>)
-    ).toThrow(
-      '[i18n] Missing key or locale: namespace "default", key "login_button" [fr] (fallback chain: fr)'
-    );
-    expect(() => provider.get("billing", "login_button" as "empty_label", "en")).toThrow(
-      '[i18n] Missing key or locale: namespace "billing", key "login_button" [en] (fallback chain: en)'
-    );
-  });
+  it("adds namespace to dictionary on first applyLoadMergeNamespace", () => {
+    const partial = new IcuTranslationProviderMulti<TestSchema, TestParams>({});
+    expect("billing" in partial.getAll()).toBe(false);
 
-  it("throws when required parameters are missing", () => {
-    expect(() => provider.get("billing", "invoice_summary", "en", { count: 1 } as never)).toThrow(
-      "[i18n Formatting Error]"
-    );
+    partial.applyLoadMergeNamespace("billing", dictionary.billing);
+    expect("billing" in partial.getAll()).toBe(true);
   });
 
-  it("patches a single namespace with setNamespace and invalidates its cache", () => {
-    const local = new IcuTranslationProviderMulti<TestSchema, TestParams>(dictionary);
-    expect(local.get("billing", "invoice_summary", "en", { count: 2, name: "Bob" })).toBe(
-      "You have 2 invoices for Bob"
+  it("accumulates a locale via applyLoadMergeNamespace when the namespace already exists", () => {
+    const local = new IcuTranslationProviderMulti<TestSchema, TestParams>({
+      billing: {
+        invoice_summary: {
+          en: "You have {count, plural, one {1 invoice} other {{count} invoices}} for {name}",
+        },
+      },
+    });
+    const view = () => local.toScope({ namespaces: ["billing"] });
+
+    expect("billing" in local.getAll()).toBe(true);
+    expect(view().t("billing", "invoice_summary", "en", { count: 1, name: "Ada" })).toBe(
+      "You have 1 invoice for Ada"
     );
 
-    local.setNamespace("billing", {
-      ...dictionary.billing,
+    local.applyLoadMergeNamespace("billing", {
       invoice_summary: {
-        en: "{count, plural, one {1 bill} other {{count} bills}}",
-        it: dictionary.billing.invoice_summary.it,
+        it: "Hai {count, plural, one {1 fattura} other {{count} fatture}} per {name}",
       },
     });
 
-    expect(local.get("billing", "invoice_summary", "en", { count: 2, name: "Bob" })).toBe(
-      "2 bills"
+    expect(view().t("billing", "invoice_summary", "en", { count: 2, name: "Bob" })).toBe(
+      "You have 2 invoices for Bob"
+    );
+    expect(view().t("billing", "invoice_summary", "it", { count: 2, name: "Bob" })).toBe(
+      "Hai 2 fatture per Bob"
     );
-    expect(local.get("default", "login_button", "en")).toBe("Login");
   });
 
-  it("merges locales per key with mergeNamespace without dropping existing locales", () => {
+  it("merges locales per key with applyLoadMergeNamespace without dropping existing locales", () => {
     const local = new IcuTranslationProviderMulti<TestSchema, TestParams>({
       billing: {
-        // @ts-expect-error missing locale
         invoice_summary: {
           en: "You have {count, plural, one {1 invoice} other {{count} invoices}} for {name}",
         },
       },
     });
+    const view = () => local.toScope({ namespaces: ["billing"] });
 
-    local.mergeNamespace("billing", {
-      // @ts-expect-error missing locale
+    local.applyLoadMergeNamespace("billing", {
       invoice_summary: {
         it: "Hai {count, plural, one {1 fattura} other {{count} fatture}} per {name}",
       },
     });
 
-    expect(local.get("billing", "invoice_summary", "en", { count: 2, name: "Bob" })).toBe(
+    expect(view().t("billing", "invoice_summary", "en", { count: 2, name: "Bob" })).toBe(
       "You have 2 invoices for Bob"
     );
-    expect(local.get("billing", "invoice_summary", "it", { count: 2, name: "Bob" })).toBe(
+    expect(view().t("billing", "invoice_summary", "it", { count: 2, name: "Bob" })).toBe(
       "Hai 2 fatture per Bob"
     );
   });
 
-  it("replaces the full dictionary on setAll", () => {
+  it("patches a preloaded default namespace key", () => {
     const local = new IcuTranslationProviderMulti<TestSchema, TestParams>(dictionary);
 
-    local.setAll({
-      ...dictionary,
-      default: {
-        ...dictionary.default,
-        login_button: { en: "Sign in", it: "Entra" },
-      },
-    });
+    local.patchKeyMulti("default", "login_button", "en", "Sign in");
 
-    expect(local.get("default", "login_button", "en")).toBe("Sign in");
+    expect(local.toScope({ namespaces: ["default"] }).t("default", "login_button", "en")).toBe(
+      "Sign in"
+    );
   });
 
-  it("merges namespaces with mergeAll without dropping existing locales", () => {
+  it("merges namespaces with applyLoadMergeAll without dropping existing locales", () => {
     const local = new IcuTranslationProviderMulti<TestSchema, TestParams>({
       billing: {
-        // @ts-expect-error missing locale
         invoice_summary: {
           en: "You have {count, plural, one {1 invoice} other {{count} invoices}} for {name}",
         },
       },
     });
+    const view = () => local.toScope({ namespaces: ["default", "billing"] });
 
-    local.mergeAll({
+    local.applyLoadMergeAll({
       billing: {
-        // @ts-expect-error missing locale
         invoice_summary: {
           it: "Hai {count, plural, one {1 fattura} other {{count} fatture}} per {name}",
         },
@@ -269,123 +210,28 @@ describe("IcuTranslationProviderMulti", () => {
       default: dictionary.default,
     });
 
-    expect(local.get("billing", "invoice_summary", "en", { count: 2, name: "Bob" })).toBe(
+    expect(view().t("billing", "invoice_summary", "en", { count: 2, name: "Bob" })).toBe(
       "You have 2 invoices for Bob"
     );
-    expect(local.get("billing", "invoice_summary", "it", { count: 2, name: "Bob" })).toBe(
+    expect(view().t("billing", "invoice_summary", "it", { count: 2, name: "Bob" })).toBe(
       "Hai 2 fatture per Bob"
     );
-    expect(local.get("default", "login_button", "en")).toBe("Login");
+    expect(view().t("default", "login_button", "en")).toBe("Login");
   });
 
   it("returns a deep-frozen snapshot from getAll", () => {
-    expect(provider.getAll()).toEqual(dictionary);
-    expect(provider.getAll()).not.toBe(dictionary);
-    expect(Object.isFrozen(provider.getAll().default)).toBe(true);
+    expect(engine.getAll()).toEqual(dictionary);
+    expect(engine.getAll()).not.toBe(dictionary);
+    expect(Object.isFrozen(engine.getAll().default)).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.default.login_button.en = "Hacked";
     }).toThrow(TypeError);
-    expect(provider.get("default", "login_button", "en")).toBe("Login");
-  });
-
-  describe("forLocale", () => {
-    it("binds a locale so get() no longer requires it", () => {
-      const it = provider.forLocale("it");
-
-      expect(it.locale).toBe("it");
-      expect(it.get("default", "login_button")).toBe("Accedi");
-      expect(it.get("billing", "invoice_summary", { count: 2, name: "Ada" })).toBe(
-        "Hai 2 fatture per Ada"
-      );
-    });
-  });
-
-  describe("locale fallback", () => {
-    const fallbackMap = {
-      en: null,
-      "de-DE": "en",
-      "de-CH": "de-DE",
-      it: "en",
-    } as const;
-
-    const fallbackProvider = new IcuTranslationProviderMulti<
-      TestSchema,
-      TestParams,
-      keyof typeof fallbackMap | LocaleOfMulti<TestSchema>,
-      typeof fallbackMap
-    >(dictionary, { localeFallback: fallbackMap });
-
-    it("resolves a locale through the fallback chain", () => {
-      expect(fallbackProvider.get("default", "login_button", "de-CH")).toBe("Login");
-    });
-
-    it("throws when the fallback chain cannot resolve a template", () => {
-      const unresolvedFallback = {
-        en: null,
-        "de-CH": "fr",
-        fr: null,
-      } as const;
-      const unresolvedProvider = new IcuTranslationProviderMulti<
-        TestSchema,
-        TestParams,
-        keyof typeof unresolvedFallback | LocaleOfMulti<TestSchema>,
-        typeof unresolvedFallback
-      >(dictionary, { localeFallback: unresolvedFallback });
-
-      expect(() => unresolvedProvider.get("default", "login_button", "de-CH")).toThrow(
-        '[i18n] Missing key or locale: namespace "default", key "login_button" [de-CH] (fallback chain: de-CH → fr)'
-      );
-    });
-  });
-
-  describe("onMissing", () => {
-    it('returns "namespace.key" with onMissing: "key"', () => {
-      const local = new IcuTranslationProviderMulti<TestSchema, TestParams>(dictionary, {
-        onMissing: "key",
-      });
-      expect(local.get("default", "missing_key" as "login_button", "en")).toBe(
-        "default.missing_key"
-      );
-    });
-
-    it("calls a custom handler with namespace, key, locale, and fallback chain", () => {
-      const contexts: unknown[] = [];
-      const local = new IcuTranslationProviderMulti<TestSchema, TestParams>(dictionary, {
-        onMissing: (context) => {
-          contexts.push(context);
-          return `<missing:${context.namespace}/${context.key}>`;
-        },
-      });
-
-      expect(local.get("default", "missing_key" as "login_button", "en")).toBe(
-        "<missing:default/missing_key>"
-      );
-      expect(contexts).toEqual([
-        { namespace: "default", key: "missing_key", locale: "en", fallbackChain: "en" },
-      ]);
-    });
-
-    it("still throws for unloaded namespaces with a lenient onMissing", () => {
-      const local = new IcuTranslationProviderMulti<TestSchema, TestParams>(
-        { default: dictionary.default },
-        { onMissing: "key" }
-      );
-      expect(() => local.get("billing", "account_balance", "en", { amount: 1 })).toThrow(
-        '[i18n] Namespace not loaded: "billing"'
-      );
-    });
-
-    it("applies onMissing through forLocale wrappers", () => {
-      const local = new IcuTranslationProviderMulti<TestSchema, TestParams>(dictionary, {
-        onMissing: "key",
-      });
-      expect(local.forLocale("en").get("default", "missing_key" as "login_button")).toBe(
-        "default.missing_key"
-      );
-    });
+    expect(engine.toScope({ namespaces: ["default"] }).t("default", "login_button", "en")).toBe(
+      "Login"
+    );
   });
 });