@xndrjs/i18n 0.2.0-alpha.0

package/src/codegen/icu-analysis.ts

@@ -0,0 +1,88 @@
+import fs from "node:fs";
+import path from "node:path";
+import { parse } from "@formatjs/icu-messageformat-parser";
+import {
+  extractVariables,
+  mergeVariableSpecs,
+  type VariableSpec,
+} from "../icu/extract-variables.js";
+import type { DictionaryJson, NamespaceEntry } from "./types.js";
+
+export function paramsTypeForVariables(variables: VariableSpec): string {
+  const keys = Object.keys(variables);
+  if (keys.length === 0) {
+    return "never";
+  }
+
+  const props = keys.map((key) => {
+    const type = variables[key] === "date" ? "Date | number" : variables[key];
+    return `${key}: ${type}`;
+  });
+  return `{ ${props.join("; ")} }`;
+}
+
+export interface DictionaryAnalysis {
+  paramsByNamespace: Record<string, Record<string, string>>;
+  argsSpecByNamespace: Record<string, Record<string, VariableSpec>>;
+  locales: Set<string>;
+}
+
+export function analyzeDictionaries(
+  projectRoot: string,
+  entries: NamespaceEntry[]
+): { ok: true; analysis: DictionaryAnalysis } | { ok: false } {
+  const paramsByNamespace: Record<string, Record<string, string>> = {};
+  const argsSpecByNamespace: Record<string, Record<string, VariableSpec>> = {};
+  const locales = new Set<string>();
+  let hasErrors = false;
+
+  for (const entry of entries) {
+    const absolutePath = path.resolve(projectRoot, entry.filePath);
+
+    if (!fs.existsSync(absolutePath)) {
+      console.error(
+        `[Codegen Error] Dictionary file not found for namespace "${entry.namespace}": ${absolutePath}`
+      );
+      hasErrors = true;
+      continue;
+    }
+
+    const dictionary = JSON.parse(fs.readFileSync(absolutePath, "utf8")) as DictionaryJson;
+    paramsByNamespace[entry.namespace] = {};
+    argsSpecByNamespace[entry.namespace] = {};
+
+    for (const [key, localesByKey] of Object.entries(dictionary)) {
+      const variables: VariableSpec = {};
+
+      for (const locale of Object.keys(localesByKey)) {
+        locales.add(locale);
+      }
+
+      for (const [locale, template] of Object.entries(localesByKey)) {
+        try {
+          const ast = parse(template);
+          const extracted = extractVariables(ast);
+          Object.assign(variables, mergeVariableSpecs(variables, extracted));
+        } catch (error) {
+          hasErrors = true;
+          const message = error instanceof Error ? error.message : String(error);
+          console.error(
+            `[Codegen Error] ICU syntax error — namespace "${entry.namespace}", key "${key}", locale "${locale}": ${message}`
+          );
+        }
+      }
+
+      paramsByNamespace[entry.namespace]![key] = paramsTypeForVariables(variables);
+      argsSpecByNamespace[entry.namespace]![key] = variables;
+    }
+  }
+
+  if (hasErrors) {
+    return { ok: false };
+  }
+
+  return {
+    ok: true,
+    analysis: { paramsByNamespace, argsSpecByNamespace, locales },
+  };
+}

package/src/codegen/locale-fallback.ts

@@ -0,0 +1,64 @@
+import { validateLocaleFallback } from "../resolve-locale.js";
+
+export function collectRequestLocales(
+  dictionaryLocales: Set<string>,
+  fallback?: Record<string, string | null>
+): Set<string> {
+  const all = new Set(dictionaryLocales);
+  if (!fallback) {
+    return all;
+  }
+
+  for (const [locale, target] of Object.entries(fallback)) {
+    all.add(locale);
+    if (target !== null) {
+      all.add(target);
+    }
+  }
+
+  return all;
+}
+
+export function validateCodegenLocaleFallback(
+  fallback: Record<string, string | null>,
+  dictionaryLocales: Set<string>
+): boolean {
+  let hasErrors = false;
+
+  try {
+    validateLocaleFallback(fallback);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(`[Codegen Error] ${message}`);
+    hasErrors = true;
+  }
+
+  for (const [locale, target] of Object.entries(fallback)) {
+    if (target !== null && !(target in fallback) && !dictionaryLocales.has(target)) {
+      console.error(
+        `[Codegen Error] localeFallback: "${locale}" points to "${target}" which is not defined in the fallback map or dictionary locales`
+      );
+      hasErrors = true;
+    }
+  }
+
+  return hasErrors;
+}
+
+export function formatLocaleFallbackBlock(
+  fallback: Record<string, string | null>,
+  constName: string,
+  typeName: string
+): string {
+  const lines = Object.entries(fallback)
+    .map(
+      ([locale, target]) =>
+        `  ${JSON.stringify(locale)}: ${target === null ? "null" : JSON.stringify(target)},`
+    )
+    .join("\n");
+
+  return (
+    `export const ${constName} = {\n${lines}\n} as const satisfies Record<string, string | null>;\n\n` +
+    `export type ${typeName} = typeof ${constName};\n\n`
+  );
+}

package/src/codegen/paths.ts

@@ -0,0 +1,27 @@
+import path from "node:path";
+
+export const GENERATED_FILE_BANNER = "// Automatically generated code. Do not edit manually.\n";
+
+export function fail(message: string): never {
+  console.error(message);
+  process.exit(1);
+  throw new Error(message);
+}
+
+export function toImportPath(fromFile: string, toFile: string): string {
+  const relative = path.relative(path.dirname(fromFile), toFile).replace(/\\/g, "/");
+  const withoutExt = relative.replace(/\.json$/, "");
+  return withoutExt.startsWith(".") ? withoutExt : `./${withoutExt}`;
+}
+
+export function toModuleBasename(filePath: string): string {
+  return path.basename(filePath).replace(/\.ts$/, "");
+}
+
+export function toImportIdentifier(namespace: string): string {
+  const safe = namespace.replace(/[^a-zA-Z0-9_$]/g, "_");
+  if (/^[0-9]/.test(safe)) {
+    return `ns_${safe}`;
+  }
+  return `${safe}Ns`;
+}

package/src/codegen/types.ts

@@ -0,0 +1,30 @@
+export interface CodegenConfig {
+  dictionary?: string;
+  namespaces?: Record<string, string>;
+  defaultNamespace?: string;
+  typesOutput: string;
+  dictionaryOutput: string;
+  instanceOutput: string;
+  dictionarySchemaOutput?: string;
+  loadOnInit?: string[];
+  namespaceLoadersOutput?: string;
+  paramsTypeName: string;
+  schemaTypeName: string;
+  localeTypeName?: string;
+  localeFallbackConstName?: string;
+  localeFallback?: Record<string, string | null>;
+  factoryName?: string;
+}
+
+export interface NamespaceEntry {
+  namespace: string;
+  filePath: string;
+}
+
+export type DictionaryJson = Record<string, Record<string, string>>;
+
+export interface LoadOnInitResolution {
+  loadOnInitSet: Set<string>;
+  lazyEntries: NamespaceEntry[];
+  hasLazy: boolean;
+}

package/src/deep-freeze.test.ts

@@ -0,0 +1,27 @@
+import { describe, expect, it } from "vitest";
+import { cloneAndFreeze, deepFreeze } from "./deep-freeze.js";
+
+describe("deepFreeze", () => {
+  it("freezes nested objects", () => {
+    const value = { welcome: { en: "Hello" } };
+    deepFreeze(value);
+
+    expect(Object.isFrozen(value)).toBe(true);
+    expect(Object.isFrozen(value.welcome)).toBe(true);
+    expect(() => {
+      value.welcome.en = "Hacked";
+    }).toThrow(TypeError);
+  });
+});
+
+describe("cloneAndFreeze", () => {
+  it("returns a deep-frozen clone", () => {
+    const source = { welcome: { en: "Hello" } };
+    const snapshot = cloneAndFreeze(source);
+
+    expect(snapshot).toEqual(source);
+    expect(snapshot).not.toBe(source);
+    expect(Object.isFrozen(snapshot)).toBe(true);
+    expect(Object.isFrozen(snapshot.welcome)).toBe(true);
+  });
+});

package/src/deep-freeze.ts

@@ -0,0 +1,17 @@
+export function deepFreeze<T>(value: T): T {
+  if (value === null || typeof value !== "object") {
+    return value;
+  }
+
+  Object.freeze(value);
+
+  for (const child of Object.values(value)) {
+    deepFreeze(child);
+  }
+
+  return value;
+}
+
+export function cloneAndFreeze<T>(value: T): T {
+  return deepFreeze(structuredClone(value));
+}

package/src/ensure-namespace.integration.test.ts

@@ -0,0 +1,66 @@
+import { describe, expect, it } from "vitest";
+import { ensureNamespacesLoadedImpl } from "./ensure-namespace.js";
+import { IcuTranslationProviderMulti } from "./IcuTranslationProviderMulti.js";
+
+type TestSchema = {
+  default: {
+    login_button: { en: string };
+  };
+  user: {
+    greeting: { en: string };
+  };
+  billing: {
+    invoice_summary: { en: string };
+  };
+};
+
+type TestParams = {
+  default: { login_button: never };
+  user: { greeting: { name: string } };
+  billing: { invoice_summary: { count: number } };
+};
+
+const namespaces: TestSchema = {
+  default: { login_button: { en: "Login" } },
+  user: { greeting: { en: "Hello {name}!" } },
+  billing: {
+    invoice_summary: {
+      en: "You have {count, plural, one {1 invoice} other {{count} invoices}}",
+    },
+  },
+};
+
+describe("ensureNamespacesLoadedImpl integration", () => {
+  it("mirrors the lazy codegen flow: partial init, preload batch, sync get", async () => {
+    const i18n = new IcuTranslationProviderMulti<TestSchema, TestParams>({
+      default: namespaces.default,
+    });
+
+    expect(i18n.hasNamespace("default")).toBe(true);
+    expect(i18n.hasNamespace("user")).toBe(false);
+    expect(i18n.hasNamespace("billing")).toBe(false);
+
+    expect(i18n.get("default", "login_button", "en")).toBe("Login");
+
+    expect(() => i18n.get("billing", "invoice_summary", "en", { count: 1 })).toThrow(
+      'Namespace not loaded: "billing"'
+    );
+
+    await ensureNamespacesLoadedImpl(
+      {
+        provider: i18n,
+        resolveLoader: (namespace) => async () => namespaces[namespace],
+        validate: (_namespace, raw) => ({ ok: true, data: raw as TestSchema["billing"] }),
+      },
+      ["user", "billing"]
+    );
+
+    expect(i18n.get("user", "greeting", "en", { name: "Ada" })).toBe("Hello Ada!");
+    expect(i18n.get("billing", "invoice_summary", "en", { count: 2 })).toBe("You have 2 invoices");
+
+    i18n.setNamespace("billing", {
+      invoice_summary: { en: "{count, plural, one {1 bill} other {{count} bills}}" },
+    });
+    expect(i18n.get("billing", "invoice_summary", "en", { count: 3 })).toBe("3 bills");
+  });
+});

package/src/ensure-namespace.test.ts

@@ -0,0 +1,125 @@
+import { describe, expect, it, vi } from "vitest";
+import { ensureNamespacesLoadedImpl } from "./ensure-namespace.js";
+import { IcuTranslationProviderMulti } from "./IcuTranslationProviderMulti.js";
+import type { ValidationResult } from "./validation/types.js";
+
+type TestSchema = {
+  default: {
+    hello: { en: string };
+  };
+  billing: {
+    invoice: { en: string };
+  };
+};
+
+type TestParams = {
+  default: { hello: never };
+  billing: { invoice: never };
+};
+
+const defaultNs: TestSchema["default"] = { hello: { en: "Hello" } };
+const billingNs: TestSchema["billing"] = { invoice: { en: "Invoice" } };
+
+function createProvider(initial: Partial<TestSchema> = { default: defaultNs }) {
+  return new IcuTranslationProviderMulti<TestSchema, TestParams>(initial);
+}
+
+describe("ensureNamespacesLoadedImpl", () => {
+  it("is a noop for an empty namespaces array", async () => {
+    const provider = createProvider();
+    const load = vi.fn();
+
+    await ensureNamespacesLoadedImpl(
+      {
+        provider,
+        resolveLoader: () => load,
+        validate: () => ({ ok: true, data: billingNs }),
+      },
+      []
+    );
+
+    expect(load).not.toHaveBeenCalled();
+  });
+
+  it("is a noop when the namespace is already loaded", async () => {
+    const provider = createProvider({ default: defaultNs, billing: billingNs });
+    const load = vi.fn();
+
+    await ensureNamespacesLoadedImpl(
+      {
+        provider,
+        resolveLoader: () => load,
+        validate: () => ({ ok: true, data: billingNs }),
+      },
+      ["billing"]
+    );
+
+    expect(load).not.toHaveBeenCalled();
+  });
+
+  it("loads multiple namespaces in parallel", async () => {
+    const provider = createProvider();
+    const loadBilling = vi.fn(async () => billingNs);
+    const loadDefault = vi.fn(async () => defaultNs);
+
+    await ensureNamespacesLoadedImpl(
+      {
+        provider,
+        resolveLoader: (namespace) => (namespace === "billing" ? loadBilling : loadDefault),
+        validate: (_namespace, raw) => ({ ok: true, data: raw as TestSchema["billing"] }),
+      },
+      ["billing"]
+    );
+
+    expect(loadBilling).toHaveBeenCalledTimes(1);
+    expect(provider.hasNamespace("billing")).toBe(true);
+    expect(provider.get("billing", "invoice", "en")).toBe("Invoice");
+  });
+
+  it("dedupes concurrent requests for the same namespace", async () => {
+    const provider = createProvider();
+    let resolveLoad!: () => void;
+    const load = vi.fn(
+      () =>
+        new Promise<TestSchema["billing"]>((resolve) => {
+          resolveLoad = () => resolve(billingNs);
+        })
+    );
+
+    const options = {
+      provider,
+      resolveLoader: () => load,
+      validate: () => ({ ok: true, data: billingNs }),
+    };
+
+    const first = ensureNamespacesLoadedImpl(options, ["billing"]);
+    const second = ensureNamespacesLoadedImpl(options, ["billing"]);
+
+    resolveLoad();
+    await Promise.all([first, second]);
+
+    expect(load).toHaveBeenCalledTimes(1);
+    expect(provider.hasNamespace("billing")).toBe(true);
+  });
+
+  it("propagates validation failures without marking the namespace loaded", async () => {
+    const provider = createProvider();
+    const failed: ValidationResult<TestSchema["billing"]> = {
+      ok: false,
+      issues: [{ kind: "invalid_input", message: "bad data" }],
+    };
+
+    await expect(
+      ensureNamespacesLoadedImpl(
+        {
+          provider,
+          resolveLoader: () => async () => ({ bad: true }),
+          validate: () => failed,
+        },
+        ["billing"]
+      )
+    ).rejects.toThrow("bad data");
+
+    expect(provider.hasNamespace("billing")).toBe(false);
+  });
+});

package/src/ensure-namespace.ts

@@ -0,0 +1,70 @@
+import type { MultiDictionary } from "./types.js";
+import type { ValidationResult } from "./validation/types.js";
+import { DictionaryValidationError } from "./validation/errors.js";
+
+export interface EnsureNamespacesLoadedOptions<
+  Schema extends MultiDictionary,
+  NS extends keyof Schema & string,
+> {
+  provider: Pick<
+    { hasNamespace(namespace: NS): boolean; setNamespace(namespace: NS, values: Schema[NS]): void },
+    "hasNamespace" | "setNamespace"
+  >;
+  resolveLoader: (namespace: NS) => () => Promise<unknown>;
+  validate: (namespace: NS, raw: unknown) => ValidationResult<Schema[NS]>;
+}
+
+const inFlightByProvider = new WeakMap<object, Map<string, Promise<void>>>();
+
+async function ensureOneNamespace<Schema extends MultiDictionary, NS extends keyof Schema & string>(
+  options: EnsureNamespacesLoadedOptions<Schema, NS>,
+  namespace: NS
+): Promise<void> {
+  if (options.provider.hasNamespace(namespace)) {
+    return;
+  }
+
+  const providerKey = options.provider as object;
+  let inFlight = inFlightByProvider.get(providerKey);
+  if (!inFlight) {
+    inFlight = new Map();
+    inFlightByProvider.set(providerKey, inFlight);
+  }
+
+  const existing = inFlight.get(namespace);
+  if (existing) {
+    return existing;
+  }
+
+  const promise = (async () => {
+    try {
+      if (options.provider.hasNamespace(namespace)) {
+        return;
+      }
+
+      const raw = await options.resolveLoader(namespace)();
+      const result = options.validate(namespace, raw);
+      if (!result.ok) {
+        throw new DictionaryValidationError(result.issues);
+      }
+
+      options.provider.setNamespace(namespace, result.data);
+    } finally {
+      inFlight!.delete(namespace);
+    }
+  })();
+
+  inFlight.set(namespace, promise);
+  return promise;
+}
+
+export async function ensureNamespacesLoadedImpl<
+  Schema extends MultiDictionary,
+  NS extends keyof Schema & string,
+>(options: EnsureNamespacesLoadedOptions<Schema, NS>, namespaces: NS[]): Promise<void> {
+  if (namespaces.length === 0) {
+    return;
+  }
+
+  await Promise.all(namespaces.map((namespace) => ensureOneNamespace(options, namespace)));
+}

package/src/icu/extract-variables.ts

@@ -0,0 +1,87 @@
+import type { parse } from "@formatjs/icu-messageformat-parser";
+
+export type VariableType = "string" | "number" | "date";
+export type VariableSpec = Record<string, VariableType>;
+
+type IcuAst = ReturnType<typeof parse>;
+type IcuNode = IcuAst[number];
+
+function isNumericIcuNode(node: IcuNode): boolean {
+  if (node.type === 2) {
+    return true;
+  }
+
+  if (node.type === 6 && "pluralType" in node && node.pluralType) {
+    return true;
+  }
+
+  return false;
+}
+
+function hasVariableName(node: IcuNode): node is Extract<IcuNode, { value: string }> {
+  return "value" in node && typeof node.value === "string";
+}
+
+export function extractVariables(nodes: IcuAst): VariableSpec {
+  const variables: VariableSpec = {};
+
+  const walk = (walkNodes: IcuAst) => {
+    for (const node of walkNodes) {
+      if (node.type === 1) {
+        variables[node.value] = variables[node.value] ?? "string";
+      } else if (isNumericIcuNode(node) && hasVariableName(node)) {
+        variables[node.value] = "number";
+      } else if ((node.type === 3 || node.type === 4) && hasVariableName(node)) {
+        variables[node.value] = "date";
+      } else if (node.type === 5 && hasVariableName(node)) {
+        variables[node.value] = variables[node.value] ?? "string";
+      } else if (node.type === 6 && hasVariableName(node)) {
+        variables[node.value] = variables[node.value] ?? "string";
+      }
+
+      if ("options" in node && node.options) {
+        for (const option of Object.values(node.options)) {
+          walk(option.value);
+        }
+      }
+
+      if ("children" in node && Array.isArray(node.children)) {
+        walk(node.children);
+      }
+    }
+  };
+
+  walk(nodes);
+  return variables;
+}
+
+export function mergeVariableSpecs(target: VariableSpec, source: VariableSpec): VariableSpec {
+  const merged = { ...target };
+
+  for (const [varName, varType] of Object.entries(source)) {
+    const existing = merged[varName];
+    if (existing && existing !== varType) {
+      merged[varName] = "number";
+    } else {
+      merged[varName] = varType;
+    }
+  }
+
+  return merged;
+}
+
+export function variableSpecsEqual(a: VariableSpec, b: VariableSpec): boolean {
+  const aKeys = Object.keys(a).sort();
+  const bKeys = Object.keys(b).sort();
+
+  if (aKeys.length !== bKeys.length) {
+    return false;
+  }
+
+  return aKeys.every((key, index) => {
+    if (key !== bKeys[index]) {
+      return false;
+    }
+    return a[key] === b[key];
+  });
+}

package/src/icu/parse-template.ts

@@ -0,0 +1,24 @@
+import { parse } from "@formatjs/icu-messageformat-parser";
+import { extractVariables, type VariableSpec } from "./extract-variables.js";
+
+export type ParseTemplateSuccess = {
+  readonly ok: true;
+  readonly args: VariableSpec;
+};
+
+export type ParseTemplateFailure = {
+  readonly ok: false;
+  readonly message: string;
+};
+
+export type ParseTemplateResult = ParseTemplateSuccess | ParseTemplateFailure;
+
+export function parseTemplate(template: string): ParseTemplateResult {
+  try {
+    const ast = parse(template);
+    return { ok: true, args: extractVariables(ast) };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return { ok: false, message };
+  }
+}

package/src/index.ts

@@ -0,0 +1,32 @@
+export type {
+  TranslationProviderSingle,
+  TranslationProviderSingleForLocale,
+} from "./IcuTranslationProviderSingle.js";
+export { IcuTranslationProviderSingle } from "./IcuTranslationProviderSingle.js";
+
+export type {
+  TranslationProviderMulti,
+  TranslationProviderMultiForLocale,
+} from "./IcuTranslationProviderMulti.js";
+export { IcuTranslationProviderMulti } from "./IcuTranslationProviderMulti.js";
+
+export type {
+  IcuTranslationProviderOptions,
+  KeyDictionary,
+  LocaleDictionary,
+  LocaleFallbackMap,
+  LocaleOfMulti,
+  LocaleOfSingle,
+  MultiDictionary,
+  RequestLocale,
+} from "./types.js";
+
+export {
+  formatLocaleFallbackChain,
+  resolveLocaleTemplate,
+  validateLocaleFallback,
+} from "./resolve-locale.js";
+export type { ResolvedLocaleTemplate } from "./resolve-locale.js";
+
+export { ensureNamespacesLoadedImpl } from "./ensure-namespace.js";
+export type { EnsureNamespacesLoadedOptions } from "./ensure-namespace.js";