@xndrjs/i18n 0.8.0 → 0.8.2-alpha.0

package/src/i18n-handle.ts

@@ -1,202 +0,0 @@
-import { invokeNamespaceLoader, type NamespaceLoader } from "./builder-loaders.js";
-import type { I18nEngineMultiImpl } from "./engine.js";
-import type {
-  LocaleFallbackMap,
-  LocaleOfMulti,
-  MultiDictionary,
-  PartialKeyDictionary,
-  PartialMultiDictionary,
-} from "./types.js";
-import type { I18nScopeMultiForLocale } from "./scope-multi.js";
-import type { MultiParams, ParamsForNamespaces, SchemaForNamespaces } from "./scope-types.js";
-
-/** Engine handle accepted by {@link createI18nHandle} (with or without localeFallback). */
-type HandleEngine<
-  Schema extends MultiDictionary,
-  Params extends MultiParams<Schema>,
-  RequestLocales extends string,
-> = I18nEngineMultiImpl<Schema, Params, RequestLocales, LocaleFallbackMap | undefined>;
-
-/** Non-empty namespace list — required by {@link I18nHandle.load} / {@link I18nHandle.peek}. */
-type NonEmptyNamespaces<NS extends readonly string[]> = NS extends readonly [] ? never : NS;
-
-/** Maps a request locale to the delivery partition key (locale itself, or a custom area). */
-export type PartitionForLocale<RequestLocales extends string> = (locale: RequestLocales) => string;
-
-export type I18nHandleOptions<
-  Schema extends MultiDictionary,
-  RequestLocales extends string = LocaleOfMulti<Schema>,
-> = {
-  namespaceLoaders?: {
-    [NS in keyof Schema & string]?: NamespaceLoader<
-      PartialKeyDictionary<Schema[NS], RequestLocales> | Schema[NS]
-    >;
-  };
-  /**
-   * Resolves the loader partition for a locale.
-   * Default: identity (`locale → locale`) for split-by-locale.
-   * Custom delivery: codegen injects `locale → LOCALE_DELIVERY_AREA[locale]`.
-   */
-  partitionForLocale?: PartitionForLocale<RequestLocales>;
-};
-
-export type LoadNamespacesInput<
-  Schema extends MultiDictionary,
-  NsList extends readonly (keyof Schema & string)[],
-  Locale extends string,
-> = {
-  namespaces: NonEmptyNamespaces<NsList>;
-  locale: Locale;
-};
-
-/** Locale-bound scope returned by {@link I18nHandle.load} / {@link I18nHandle.peek}. */
-export type ScopeForLocale<
-  Schema extends MultiDictionary,
-  Params extends MultiParams<Schema>,
-  RequestLocales extends string,
-  NsList extends readonly (keyof Schema & string)[],
-  Locale extends RequestLocales,
-> = I18nScopeMultiForLocale<
-  SchemaForNamespaces<Schema, NsList>,
-  ParamsForNamespaces<Schema, Params, NsList>,
-  RequestLocales,
-  Locale
->;
-
-/**
- * Single runtime handle: pass `namespaces` + `locale`; partition is derived via
- * {@link I18nHandleOptions.partitionForLocale}.
- */
-export interface I18nHandle<
-  Schema extends MultiDictionary,
-  Params extends MultiParams<Schema>,
-  RequestLocales extends string = LocaleOfMulti<Schema>,
-> {
-  load<const NsList extends readonly (keyof Schema & string)[], Locale extends RequestLocales>(
-    input: LoadNamespacesInput<Schema, NsList, Locale>
-  ): Promise<ScopeForLocale<Schema, Params, RequestLocales, NsList, Locale>>;
-
-  /**
-   * Sync scope when every requested resource is already marked loaded (e.g. hydrate seed).
-   * Returns `null` when a normal async {@link load} is still required.
-   */
-  peek<const NsList extends readonly (keyof Schema & string)[], Locale extends RequestLocales>(
-    input: LoadNamespacesInput<Schema, NsList, Locale>
-  ): ScopeForLocale<Schema, Params, RequestLocales, NsList, Locale> | null;
-
-  /** Dictionary (loaded namespaces) + resources for SSR→CSR hydrate. */
-  serialize(): {
-    dictionary: PartialMultiDictionary<Schema, RequestLocales>;
-    resources: readonly (readonly [string, string])[];
-  };
-}
-
-export class I18nHandleImpl<
-  Schema extends MultiDictionary,
-  Params extends MultiParams<Schema>,
-  RequestLocales extends string = LocaleOfMulti<Schema>,
-> implements I18nHandle<Schema, Params, RequestLocales> {
-  private readonly partitionForLocale: PartitionForLocale<RequestLocales>;
-
-  constructor(
-    private readonly engine: HandleEngine<Schema, Params, RequestLocales>,
-    private readonly options?: I18nHandleOptions<Schema, RequestLocales>
-  ) {
-    this.partitionForLocale = options?.partitionForLocale ?? ((locale) => locale);
-  }
-
-  async load<
-    const NsList extends readonly (keyof Schema & string)[],
-    Locale extends RequestLocales,
-  >(
-    input: LoadNamespacesInput<Schema, NsList, Locale>
-  ): Promise<ScopeForLocale<Schema, Params, RequestLocales, NsList, Locale>> {
-    await applyHandleLoad(this.engine, this.options, input, this.partitionForLocale);
-    return this.engine.toScope({ namespaces: input.namespaces }).forLocale(input.locale);
-  }
-
-  peek<const NsList extends readonly (keyof Schema & string)[], Locale extends RequestLocales>(
-    input: LoadNamespacesInput<Schema, NsList, Locale>
-  ): ScopeForLocale<Schema, Params, RequestLocales, NsList, Locale> | null {
-    if (!areHandleResourcesReady(this.engine, this.options, input, this.partitionForLocale)) {
-      return null;
-    }
-    return this.engine.toScope({ namespaces: input.namespaces }).forLocale(input.locale);
-  }
-
-  serialize() {
-    return this.engine.serialize();
-  }
-}
-
-export function createI18nHandle<
-  Schema extends MultiDictionary,
-  Params extends MultiParams<Schema>,
-  RequestLocales extends string = LocaleOfMulti<Schema>,
->(
-  engine: HandleEngine<Schema, Params, RequestLocales>,
-  options?: I18nHandleOptions<Schema, RequestLocales>
-): I18nHandle<Schema, Params, RequestLocales> {
-  return new I18nHandleImpl(engine, options);
-}
-
-function areHandleResourcesReady<
-  Schema extends MultiDictionary,
-  Params extends MultiParams<Schema>,
-  RequestLocales extends string,
-  NsList extends readonly (keyof Schema & string)[],
-  Locale extends RequestLocales,
->(
-  engine: HandleEngine<Schema, Params, RequestLocales>,
-  options: I18nHandleOptions<Schema, RequestLocales> | undefined,
-  input: LoadNamespacesInput<Schema, NsList, Locale>,
-  partitionForLocale: PartitionForLocale<RequestLocales>
-): boolean {
-  if (input.namespaces.length === 0) {
-    return false;
-  }
-  const partition = partitionForLocale(input.locale);
-  return input.namespaces.every((namespace) => {
-    const loader = options?.namespaceLoaders?.[namespace];
-    if (loader === undefined) {
-      return true;
-    }
-    return engine.hasBuilderResourceLoaded(namespace, partition);
-  });
-}
-
-async function applyHandleLoad<
-  Schema extends MultiDictionary,
-  Params extends MultiParams<Schema>,
-  RequestLocales extends string,
-  NsList extends readonly (keyof Schema & string)[],
-  Locale extends RequestLocales,
->(
-  engine: HandleEngine<Schema, Params, RequestLocales>,
-  options: I18nHandleOptions<Schema, RequestLocales> | undefined,
-  input: LoadNamespacesInput<Schema, NsList, Locale>,
-  partitionForLocale: PartitionForLocale<RequestLocales>
-): Promise<void> {
-  if (input.namespaces.length === 0) {
-    throw new Error("[i18n] load() requires a non-empty namespaces array.");
-  }
-
-  const partition = partitionForLocale(input.locale);
-
-  await Promise.all(
-    input.namespaces.map(async (namespace) => {
-      const loader = options?.namespaceLoaders?.[namespace];
-      if (loader === undefined) {
-        return;
-      }
-
-      if (engine.hasBuilderResourceLoaded(namespace, partition)) {
-        return;
-      }
-
-      const data = await invokeNamespaceLoader(loader, partition, { locale: input.locale });
-      engine.applyLoadMergeNamespace(namespace, data);
-      engine.markBuilderResourceLoaded(namespace, partition);
-    })
-  );
-}

package/src/icu/extract-variables.test.ts

@@ -1,199 +0,0 @@
-import { parse } from "@formatjs/icu-messageformat-parser";
-import { describe, expect, it } from "vitest";
-import {
-  extractVariableMeta,
-  inferMergedVariableType,
-  mergeVariableMetaAcrossLocales,
-  variableMetaToSpec,
-  type VariableRole,
-} from "./extract-variables.js";
-
-function metaFor(template: string) {
-  return extractVariableMeta(parse(template));
-}
-
-function mergeTemplates(...templates: string[]) {
-  return mergeVariableMetaAcrossLocales(templates.map((template) => metaFor(template)));
-}
-
-function roles(...items: VariableRole[]) {
-  return new Set(items);
-}
-
-describe("inferMergedVariableType", () => {
-  describe("string family", () => {
-    it.each<[VariableRole[], "string"]>([
-      [["simple"], "string"],
-      [["select"], "string"],
-      [["simple", "select"], "string"],
-    ])("accepts %j → %s", (items, expected) => {
-      expect(inferMergedVariableType(roles(...items))).toBe(expected);
-    });
-  });
-
-  describe("number family", () => {
-    it.each<[VariableRole[], "number"]>([
-      [["plural"], "number"],
-      [["selectordinal"], "number"],
-      [["number"], "number"],
-      [["simple", "plural"], "number"],
-      [["simple", "selectordinal"], "number"],
-      [["simple", "number"], "number"],
-      [["plural", "number"], "number"],
-      [["selectordinal", "number"], "number"],
-    ])("accepts %j → %s", (items, expected) => {
-      expect(inferMergedVariableType(roles(...items))).toBe(expected);
-    });
-  });
-
-  describe("date family", () => {
-    it.each<[VariableRole[], "date"]>([
-      [["date"], "date"],
-      [["time"], "date"],
-      [["date", "time"], "date"],
-    ])("accepts %j → %s", (items, expected) => {
-      expect(inferMergedVariableType(roles(...items))).toBe(expected);
-    });
-  });
-
-  describe("conflicts", () => {
-    it.each<{ label: string; roles: VariableRole[] }>([
-      { label: "plural + select", roles: ["plural", "select"] },
-      { label: "selectordinal + select", roles: ["selectordinal", "select"] },
-      { label: "plural + selectordinal", roles: ["plural", "selectordinal"] },
-      { label: "select + number", roles: ["select", "number"] },
-      { label: "select + simple + number", roles: ["select", "simple", "number"] },
-      { label: "plural + simple + select", roles: ["plural", "simple", "select"] },
-      { label: "date + simple", roles: ["date", "simple"] },
-      { label: "date + plural", roles: ["date", "plural"] },
-      { label: "time + select", roles: ["time", "select"] },
-      { label: "date + number", roles: ["date", "number"] },
-    ])("rejects $label", ({ roles: roleList }) => {
-      expect(inferMergedVariableType(roles(...roleList))).toBe("CONFLICT");
-    });
-  });
-});
-
-describe("mergeVariableMetaAcrossLocales", () => {
-  describe("compatible cross-locale merges", () => {
-    it("infers string for simple interpolation in every locale", () => {
-      const result = mergeTemplates("Welcome {name}!", "Benvenuto {name}!");
-
-      expect(result).toEqual({ ok: true, merged: { name: "string" } });
-    });
-
-    it("infers string when one locale uses select and another uses simple interpolation", () => {
-      const result = mergeTemplates(
-        "{gender, select, female {she} other {they}}",
-        "Pronome: {gender}"
-      );
-
-      expect(result).toEqual({ ok: true, merged: { gender: "string" } });
-      expect(variableMetaToSpec(metaFor("Pronome: {gender}"))).toEqual({ gender: "string" });
-      expect(variableMetaToSpec(metaFor("{gender, select, other {x}}"))).toEqual({
-        gender: "string",
-      });
-    });
-
-    it("infers number when English uses plural and Italian uses simple interpolation", () => {
-      const result = mergeTemplates(
-        "You have {count, plural, one {1 invoice} other {# invoices}}",
-        "Hai {count} fatture"
-      );
-
-      expect(result).toEqual({ ok: true, merged: { count: "number" } });
-      expect(variableMetaToSpec(metaFor("Hai {count} fatture"))).toEqual({ count: "string" });
-      expect(
-        variableMetaToSpec(metaFor("You have {count, plural, one {1 invoice} other {# invoices}}"))
-      ).toEqual({ count: "number" });
-    });
-
-    it("infers number when one locale uses selectordinal and another uses simple interpolation", () => {
-      const result = mergeTemplates(
-        "You finished {position, selectordinal, one {#st} other {#th}}",
-        "Sei al {position} posto"
-      );
-
-      expect(result).toEqual({ ok: true, merged: { position: "number" } });
-    });
-
-    it("infers number when one locale uses plural and another uses number format", () => {
-      const result = mergeTemplates(
-        "{amount, plural, one {1} other {#}}",
-        "Totale: {amount, number}"
-      );
-
-      expect(result).toEqual({ ok: true, merged: { amount: "number" } });
-    });
-
-    it("infers date when locales use date and time on the same variable", () => {
-      const result = mergeTemplates("{due, date, short}", "{due, time, short}");
-
-      expect(result).toEqual({ ok: true, merged: { due: "date" } });
-    });
-  });
-
-  describe("incompatible cross-locale merges", () => {
-    it("rejects plural and select on the same variable", () => {
-      const result = mergeTemplates(
-        "{myVar, select, other {x}}",
-        "{myVar, plural, one {1} other {#}}"
-      );
-
-      expect(result.ok).toBe(false);
-      if (!result.ok) {
-        expect(result.message).toContain('Incompatible ICU variable "myVar"');
-      }
-    });
-
-    it("rejects plural and selectordinal on the same variable", () => {
-      const result = mergeTemplates(
-        "{rank, plural, one {1} other {#}}",
-        "{rank, selectordinal, one {#st} other {#th}}"
-      );
-
-      expect(result.ok).toBe(false);
-      if (!result.ok) {
-        expect(result.message).toContain('Incompatible ICU variable "rank"');
-        expect(result.message).toContain("plural");
-        expect(result.message).toContain("selectordinal");
-      }
-    });
-
-    it("rejects select and number format on the same variable", () => {
-      const result = mergeTemplates("{value, select, other {x}}", "Valore: {value, number}");
-
-      expect(result.ok).toBe(false);
-      if (!result.ok) {
-        expect(result.message).toContain('Incompatible ICU variable "value"');
-      }
-    });
-
-    it("rejects date and simple interpolation on the same variable", () => {
-      const result = mergeTemplates("{due, date, short}", "Scadenza {due}");
-
-      expect(result.ok).toBe(false);
-      if (!result.ok) {
-        expect(result.message).toContain('Incompatible ICU variable "due"');
-      }
-    });
-
-    it("rejects different variable names across locales", () => {
-      const result = mergeTemplates("Welcome {name}!", "Benvenuto {nome}!");
-
-      expect(result.ok).toBe(false);
-      if (!result.ok) {
-        expect(result.message).toContain("Inconsistent ICU variable names across locales");
-      }
-    });
-
-    it("rejects when one locale omits a variable present in another", () => {
-      const result = mergeTemplates("Welcome {name}!", "{name} and {count}");
-
-      expect(result.ok).toBe(false);
-      if (!result.ok) {
-        expect(result.message).toContain("Inconsistent ICU variable names across locales");
-      }
-    });
-  });
-});

package/src/icu/extract-variables.ts

@@ -1,227 +0,0 @@
-import type { parse } from "@formatjs/icu-messageformat-parser";
-
-export type VariableType = "string" | "number" | "date";
-export type VariableSpec = Record<string, VariableType>;
-
-export type VariableRole =
-  | "simple"
-  | "plural"
-  | "selectordinal"
-  | "select"
-  | "number"
-  | "date"
-  | "time";
-
-export type VariableMeta = {
-  type: VariableType;
-  roles: Set<VariableRole>;
-};
-
-export type VariableMetaSpec = Record<string, VariableMeta>;
-
-type IcuAst = ReturnType<typeof parse>;
-type IcuNode = IcuAst[number];
-
-function isPluralOrOrdinalNode(node: IcuNode): node is Extract<IcuNode, { type: 6 }> {
-  return node.type === 6 && "pluralType" in node && Boolean(node.pluralType);
-}
-
-function hasVariableName(node: IcuNode): node is Extract<IcuNode, { value: string }> {
-  return "value" in node && typeof node.value === "string";
-}
-
-function addVariableMeta(
-  variables: VariableMetaSpec,
-  name: string,
-  type: VariableType,
-  role: VariableRole
-): void {
-  const existing = variables[name];
-  if (!existing) {
-    variables[name] = { type, roles: new Set([role]) };
-    return;
-  }
-
-  existing.roles.add(role);
-  existing.type = mergeVariableTypes(existing.type, type);
-}
-
-function mergeVariableTypes(left: VariableType, right: VariableType): VariableType {
-  if (left === right) {
-    return left;
-  }
-
-  if ((left === "string" && right === "number") || (left === "number" && right === "string")) {
-    return "number";
-  }
-
-  return right;
-}
-
-export function extractVariableMeta(nodes: IcuAst): VariableMetaSpec {
-  const variables: VariableMetaSpec = {};
-
-  const walk = (walkNodes: IcuAst) => {
-    for (const node of walkNodes) {
-      if (node.type === 1 && hasVariableName(node)) {
-        addVariableMeta(variables, node.value, "string", "simple");
-      } else if (node.type === 2 && hasVariableName(node)) {
-        addVariableMeta(variables, node.value, "number", "number");
-      } else if (isPluralOrOrdinalNode(node) && hasVariableName(node)) {
-        const role = node.pluralType === "ordinal" ? "selectordinal" : "plural";
-        addVariableMeta(variables, node.value, "number", role);
-      } else if (node.type === 3 && hasVariableName(node)) {
-        addVariableMeta(variables, node.value, "date", "date");
-      } else if (node.type === 4 && hasVariableName(node)) {
-        addVariableMeta(variables, node.value, "date", "time");
-      } else if (node.type === 5 && hasVariableName(node)) {
-        addVariableMeta(variables, node.value, "string", "select");
-      }
-
-      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 variableMetaToSpec(meta: VariableMetaSpec): VariableSpec {
-  return Object.fromEntries(Object.entries(meta).map(([name, entry]) => [name, entry.type]));
-}
-
-export function extractVariables(nodes: IcuAst): VariableSpec {
-  return variableMetaToSpec(extractVariableMeta(nodes));
-}
-
-export function inferMergedVariableType(roles: Set<VariableRole>): VariableType | "CONFLICT" {
-  const hasPlural = roles.has("plural");
-  const hasSelectordinal = roles.has("selectordinal");
-  const hasSelect = roles.has("select");
-  const hasSimple = roles.has("simple");
-  const hasNumber = roles.has("number");
-  const hasDate = roles.has("date");
-  const hasTime = roles.has("time");
-
-  // Incompatible numeric ICU constructs on the same variable.
-  if (hasPlural && hasSelectordinal) {
-    return "CONFLICT";
-  }
-
-  // Select (string-family) vs plural / ordinal / number-format (number-family).
-  if (hasSelect && (hasPlural || hasSelectordinal || hasNumber)) {
-    return "CONFLICT";
-  }
-
-  // Legacy explicit pairs — covered by the rule above, kept for clarity.
-  if (hasPlural && hasSelect) {
-    return "CONFLICT";
-  }
-
-  if (hasSelectordinal && hasSelect) {
-    return "CONFLICT";
-  }
-
-  if (hasDate || hasTime) {
-    if (hasPlural || hasSelect || hasSelectordinal || hasSimple || hasNumber) {
-      return "CONFLICT";
-    }
-    return "date";
-  }
-
-  if (hasPlural || hasSelectordinal || hasNumber) {
-    return "number";
-  }
-
-  if (hasSelect || hasSimple) {
-    return "string";
-  }
-
-  return "string";
-}
-
-export function mergeVariableMetaAcrossLocales(
-  localeMetas: readonly VariableMetaSpec[]
-): { ok: true; merged: VariableSpec } | { ok: false; message: string } {
-  const keySignatures = localeMetas.map((meta) => Object.keys(meta).sort().join(","));
-  if (new Set(keySignatures).size > 1) {
-    return {
-      ok: false,
-      message: `Inconsistent ICU variable names across locales (keys: ${keySignatures.join(" vs ")})`,
-    };
-  }
-
-  const merged: VariableSpec = {};
-  const variableNames = new Set(localeMetas.flatMap((meta) => Object.keys(meta)));
-
-  for (const variableName of variableNames) {
-    const combinedRoles = new Set<VariableRole>();
-
-    for (const meta of localeMetas) {
-      for (const role of meta[variableName]?.roles ?? []) {
-        combinedRoles.add(role);
-      }
-    }
-
-    const mergedType = inferMergedVariableType(combinedRoles);
-    if (mergedType === "CONFLICT") {
-      const rolesByLocale = localeMetas
-        .map((meta) => {
-          const entry = meta[variableName];
-          if (!entry) {
-            return null;
-          }
-          return [...entry.roles].sort().join("|");
-        })
-        .filter((value): value is string => value !== null);
-
-      return {
-        ok: false,
-        message: `Incompatible ICU variable "${variableName}" across locales (roles: ${rolesByLocale.join(" vs ")})`,
-      };
-    }
-
-    merged[variableName] = mergedType;
-  }
-
-  return { ok: true, merged };
-}
-
-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

@@ -1,31 +0,0 @@
-import { parse } from "@formatjs/icu-messageformat-parser";
-import {
-  extractVariableMeta,
-  variableMetaToSpec,
-  type VariableMetaSpec,
-  type VariableSpec,
-} from "./extract-variables.js";
-
-export type ParseTemplateSuccess = {
-  readonly ok: true;
-  readonly args: VariableSpec;
-  readonly meta: VariableMetaSpec;
-};
-
-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);
-    const meta = extractVariableMeta(ast);
-    return { ok: true, args: variableMetaToSpec(meta), meta };
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    return { ok: false, message };
-  }
-}