@xndrjs/i18n 0.7.0 → 0.8.0

package/src/codegen/emit/dictionary-file.ts

@@ -1,244 +0,0 @@
-import path from "node:path";
-import {
-  GENERATED_FILE_BANNER,
-  toImportIdentifier,
-  toImportPath,
-  toLocaleObjectKey,
-  toModuleBasename,
-  toRelativeModuleImport,
-} from "../paths.js";
-import type { DeliveryMode } from "../codegen-config-schema.js";
-import type { ImportExtension, NamespaceEntry } from "../types.js";
-
-/**
- * Emits the generated `dictionary.generated.ts` module: eager translation imports
- * wired into `defaultDictionary` or `defaultDictionaryFor`, depending on delivery mode.
- */
-export interface DictionaryFileOptions {
-  isSingle: boolean;
-  hasLazy: boolean;
-  entries: NamespaceEntry[];
-  eagerEntries: NamespaceEntry[];
-  projectRoot: string;
-  dictionaryOutputPath: string;
-  typesOutputPath: string;
-  schemaTypeName: string;
-  localeTypeName: string;
-  importExtension: ImportExtension;
-  delivery?: DeliveryMode;
-  splitPathsByNamespace?: Record<string, Record<string, string>>;
-  requestLocales?: readonly string[];
-  deliveryAreaTypeName?: string;
-  deliveryAreaNames?: readonly string[];
-}
-
-function toArtifactIdentifierSuffix(artifactKey: string): string {
-  return artifactKey
-    .split(/[^a-zA-Z0-9]+/)
-    .filter(Boolean)
-    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
-    .join("");
-}
-
-function toSplitImportIdentifier(namespace: string, artifactKey: string): string {
-  const namespaceId = toImportIdentifier(namespace).replace(/Ns$/, "");
-  return `${namespaceId}${toArtifactIdentifierSuffix(artifactKey)}`;
-}
-
-function toNamespaceBaseIdentifier(namespace: string): string {
-  return toImportIdentifier(namespace).replace(/Ns$/, "");
-}
-
-interface PartitionedDictionaryParams {
-  partitionKeys: readonly string[];
-  paramName: string;
-  paramTypeName: string;
-}
-
-function toPartitionSuffix(paramName: string): string {
-  return `By${paramName.charAt(0).toUpperCase()}${paramName.slice(1)}`;
-}
-
-/**
- * Emits dictionary source for split-by-locale and custom delivery.
- * Imports one JSON file per namespace × partition key (locale or area) and
- * exposes `defaultDictionaryFor(partition)` that selects the matching slice.
- */
-function formatPartitionedDictionaryFile(
-  options: DictionaryFileOptions,
-  { partitionKeys, paramName, paramTypeName }: PartitionedDictionaryParams
-): string | null {
-  const {
-    isSingle,
-    hasLazy,
-    eagerEntries,
-    projectRoot,
-    dictionaryOutputPath,
-    typesOutputPath,
-    schemaTypeName,
-    importExtension,
-    splitPathsByNamespace = {},
-  } = options;
-
-  const partitionSuffix = toPartitionSuffix(paramName);
-  const typesModule = toModuleBasename(typesOutputPath);
-  const typesImport = toRelativeModuleImport(typesModule, importExtension);
-  const dictionaryTypeName = hasLazy ? "InitialSchema" : schemaTypeName;
-  const schemaTypeImport = hasLazy ? `, ${schemaTypeName}` : "";
-
-  if (eagerEntries.length === 0) {
-    return null;
-  }
-
-  const imports = eagerEntries
-    .flatMap((entry) =>
-      partitionKeys.map((partitionKey) => {
-        const splitRelativePath = splitPathsByNamespace[entry.namespace]?.[partitionKey];
-        if (!splitRelativePath) {
-          throw new Error(
-            `[Codegen Error] Missing split path for namespace "${entry.namespace}", ${paramName} "${partitionKey}".`
-          );
-        }
-        const importPath = toImportPath(
-          dictionaryOutputPath,
-          path.resolve(projectRoot, splitRelativePath)
-        );
-        const importId = toSplitImportIdentifier(entry.namespace, partitionKey);
-        return `import ${importId} from '${importPath}.json';`;
-      })
-    )
-    .join("\n");
-
-  if (isSingle) {
-    const entry = eagerEntries[0]!;
-    const baseId = toNamespaceBaseIdentifier(entry.namespace);
-    const partitionEntries = partitionKeys
-      .map(
-        (partitionKey) =>
-          `  ${toLocaleObjectKey(partitionKey)}: ${toSplitImportIdentifier(entry.namespace, partitionKey)},`
-      )
-      .join("\n");
-
-    return (
-      `${GENERATED_FILE_BANNER}` +
-      `${imports}\n` +
-      `import type { ${schemaTypeName}, ${paramTypeName} } from '${typesImport}';\n\n` +
-      `const ${baseId}${partitionSuffix} = {\n${partitionEntries}\n} as const;\n\n` +
-      `export function defaultDictionaryFor(${paramName}: ${paramTypeName}): ${schemaTypeName} {\n` +
-      `  return ${baseId}${partitionSuffix}[${paramName}];\n` +
-      `}\n`
-    );
-  }
-
-  const byPartitionBlocks = eagerEntries
-    .map((entry) => {
-      const baseId = toNamespaceBaseIdentifier(entry.namespace);
-      const partitionEntries = partitionKeys
-        .map(
-          (partitionKey) =>
-            `  ${toLocaleObjectKey(partitionKey)}: ${toSplitImportIdentifier(entry.namespace, partitionKey)},`
-        )
-        .join("\n");
-      return `const ${baseId}${partitionSuffix} = {\n${partitionEntries}\n} as const;`;
-    })
-    .join("\n\n");
-
-  const objectEntries = eagerEntries
-    .map((entry) => {
-      const baseId = toNamespaceBaseIdentifier(entry.namespace);
-      return `    ${entry.namespace}: ${baseId}${partitionSuffix}[${paramName}],`;
-    })
-    .join("\n");
-
-  const importsBlock = imports.length > 0 ? `${imports}\n` : "";
-  const byPartitionBlock = byPartitionBlocks.length > 0 ? `${byPartitionBlocks}\n\n` : "";
-
-  return (
-    `${GENERATED_FILE_BANNER}` +
-    `${importsBlock}` +
-    `import type { ${dictionaryTypeName}, ${paramTypeName}${schemaTypeImport} } from '${typesImport}';\n\n` +
-    `${byPartitionBlock}` +
-    `export function defaultDictionaryFor(${paramName}: ${paramTypeName}): ${dictionaryTypeName} {\n` +
-    `  return {\n${objectEntries}\n  };\n` +
-    `}\n`
-  );
-}
-
-/**
- * Builds `dictionary.generated.ts` for the configured delivery mode:
- * canonical (single bundled JSON per namespace), split-by-locale, or custom areas.
- */
-export function formatDictionaryFile(options: DictionaryFileOptions): string | null {
-  const delivery = options.delivery ?? "canonical";
-  if (delivery === "split-by-locale") {
-    return formatPartitionedDictionaryFile(options, {
-      partitionKeys: options.requestLocales ?? [],
-      paramName: "locale",
-      paramTypeName: options.localeTypeName,
-    });
-  }
-  if (delivery === "custom") {
-    if (!options.deliveryAreaTypeName) {
-      throw new Error("[Codegen Error] deliveryAreaTypeName is required for custom delivery.");
-    }
-    return formatPartitionedDictionaryFile(options, {
-      partitionKeys: options.deliveryAreaNames ?? [],
-      paramName: "area",
-      paramTypeName: options.deliveryAreaTypeName,
-    });
-  }
-
-  const {
-    isSingle,
-    hasLazy,
-    entries,
-    eagerEntries,
-    projectRoot,
-    dictionaryOutputPath,
-    typesOutputPath,
-    schemaTypeName,
-    importExtension,
-  } = options;
-
-  const typesModule = toModuleBasename(typesOutputPath);
-  const typesImport = toRelativeModuleImport(typesModule, importExtension);
-
-  if (isSingle) {
-    const entry = entries[0]!;
-    const importPath = toImportPath(
-      dictionaryOutputPath,
-      path.resolve(projectRoot, entry.filePath)
-    );
-    const importId = toImportIdentifier(entry.namespace);
-
-    return (
-      `${GENERATED_FILE_BANNER}` +
-      `import ${importId} from '${importPath}.json';\n` +
-      `import type { ${schemaTypeName} } from '${typesImport}';\n\n` +
-      `export const defaultDictionary: ${schemaTypeName} = ${importId};\n`
-    );
-  }
-
-  const dictionaryTypeName = hasLazy ? "InitialSchema" : schemaTypeName;
-
-  const imports = eagerEntries
-    .map((entry) => {
-      const importPath = toImportPath(
-        dictionaryOutputPath,
-        path.resolve(projectRoot, entry.filePath)
-      );
-      return `import ${toImportIdentifier(entry.namespace)} from '${importPath}.json';`;
-    })
-    .join("\n");
-
-  const objectEntries = eagerEntries
-    .map((entry) => `  ${entry.namespace}: ${toImportIdentifier(entry.namespace)},`)
-    .join("\n");
-
-  return (
-    `${GENERATED_FILE_BANNER}` +
-    `${imports}\n` +
-    `import type { ${dictionaryTypeName} } from '${typesImport}';\n\n` +
-    `export const defaultDictionary: ${dictionaryTypeName} = {\n${objectEntries}\n};\n`
-  );
-}

package/src/deep-freeze.test.ts

@@ -1,40 +0,0 @@
-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);
-  });
-
-  it("does not recurse forever on cyclic structures", () => {
-    const value: { name: string; self?: unknown; child: { parent?: unknown } } = {
-      name: "root",
-      child: {},
-    };
-    value.self = value;
-    value.child.parent = value;
-
-    expect(() => deepFreeze(value)).not.toThrow();
-    expect(Object.isFrozen(value)).toBe(true);
-    expect(Object.isFrozen(value.child)).toBe(true);
-  });
-});
-
-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

@@ -1,22 +0,0 @@
-export function deepFreeze<T>(value: T): T {
-  if (value === null || typeof value !== "object") {
-    return value;
-  }
-
-  // Guards against infinite recursion on cyclic structures.
-  if (Object.isFrozen(value)) {
-    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/patch-key.test.ts

@@ -1,186 +0,0 @@
-import { describe, expect, it } from "vitest";
-import {
-  assertPatchKeyMulti,
-  assertPatchKeySingle,
-  preloadKeyMulti,
-  preloadKeySingle,
-  recordPreloadedKeysMulti,
-  recordPreloadedKeysSingle,
-  seedPreloadedKeysMulti,
-  seedPreloadedKeysSingle,
-} from "./patch-key.js";
-
-describe("preload key helpers", () => {
-  it("formats single preload keys as key:locale", () => {
-    expect(preloadKeySingle("welcome", "en")).toBe("welcome:en");
-  });
-
-  it("formats multi preload keys as namespace:key:locale", () => {
-    expect(preloadKeyMulti("billing", "invoice_summary", "it")).toBe("billing:invoice_summary:it");
-  });
-});
-
-describe("seedPreloadedKeysSingle", () => {
-  it("seeds every key/locale pair from the initial dictionary", () => {
-    const preloadedKeys = new Set<string>();
-    seedPreloadedKeysSingle(
-      {
-        login_button: { en: "Login", it: "Accedi" },
-        welcome: { en: "Welcome {name}!" },
-      },
-      preloadedKeys
-    );
-
-    expect(preloadedKeys).toEqual(new Set(["login_button:en", "login_button:it", "welcome:en"]));
-  });
-});
-
-describe("seedPreloadedKeysMulti", () => {
-  it("seeds every namespace/key/locale triple from the initial dictionary", () => {
-    const preloadedKeys = new Set<string>();
-    seedPreloadedKeysMulti(
-      {
-        default: { login_button: { en: "Login" } },
-        billing: { invoice_summary: { en: "One", it: "Uno" } },
-      },
-      preloadedKeys
-    );
-
-    expect(preloadedKeys).toEqual(
-      new Set([
-        "default:login_button:en",
-        "billing:invoice_summary:en",
-        "billing:invoice_summary:it",
-      ])
-    );
-  });
-});
-
-describe("recordPreloadedKeysSingle", () => {
-  it("records locales from a load merge payload", () => {
-    const preloadedKeys = new Set<string>();
-    recordPreloadedKeysSingle(
-      {
-        welcome: { it: "Benvenuto {name}!" },
-      },
-      preloadedKeys
-    );
-
-    expect(preloadedKeys).toEqual(new Set(["welcome:it"]));
-  });
-});
-
-describe("recordPreloadedKeysMulti", () => {
-  it("records locales from a namespace load merge payload", () => {
-    const preloadedKeys = new Set<string>();
-    recordPreloadedKeysMulti(
-      "billing",
-      {
-        invoice_summary: { it: "Hai {count} fatture" },
-      },
-      preloadedKeys
-    );
-
-    expect(preloadedKeys).toEqual(new Set(["billing:invoice_summary:it"]));
-  });
-});
-
-describe("assertPatchKeySingle", () => {
-  const preloadedKeys = new Set(["welcome:en", "welcome:it", "invoice_count:en"]);
-
-  it("accepts a valid patch for a preloaded key", () => {
-    expect(() =>
-      assertPatchKeySingle("welcome", "en", "Hello {name}!", preloadedKeys, {
-        en: "Welcome {name}!",
-        it: "Benvenuto {name}!",
-      })
-    ).not.toThrow();
-  });
-
-  it("rejects a key that was not preloaded", () => {
-    expect(() =>
-      assertPatchKeySingle("welcome", "fr", "Bonjour {name}!", preloadedKeys, {
-        en: "Welcome {name}!",
-      })
-    ).toThrow("[i18n] Key not preloaded: welcome (fr)");
-  });
-
-  it("rejects invalid ICU syntax", () => {
-    expect(() =>
-      assertPatchKeySingle("welcome", "en", "Hi {name", preloadedKeys, {
-        en: "Welcome {name}!",
-      })
-    ).toThrow("[i18n] ICU syntax error on patch:");
-  });
-
-  it("rejects incompatible ICU args against other locales for the same key", () => {
-    expect(() =>
-      assertPatchKeySingle(
-        "invoice_count",
-        "en",
-        "{count, select, other {{count}}}",
-        preloadedKeys,
-        {
-          en: "You have {count, plural, one {1 invoice} other {{count} invoices}}",
-          it: "Hai {count, plural, one {1 fattura} other {{count} fatture}}",
-        }
-      )
-    ).toThrow("[i18n] ICU args mismatch on patch:");
-  });
-});
-
-describe("assertPatchKeyMulti", () => {
-  const preloadedKeys = new Set([
-    "billing:invoice_summary:en",
-    "billing:invoice_summary:it",
-    "default:login_button:en",
-  ]);
-
-  it("accepts a valid patch for a preloaded namespace key", () => {
-    expect(() =>
-      assertPatchKeyMulti(
-        "billing",
-        "invoice_summary",
-        "en",
-        "You have {count, plural, one {1 bill} other {{count} bills}} for {name}",
-        preloadedKeys,
-        {
-          en: "You have {count, plural, one {1 invoice} other {{count} invoices}} for {name}",
-          it: "Hai {count, plural, one {1 fattura} other {{count} fatture}} per {name}",
-        }
-      )
-    ).not.toThrow();
-  });
-
-  it("rejects a namespace key that was not preloaded", () => {
-    expect(() =>
-      assertPatchKeyMulti("billing", "invoice_summary", "fr", "Facture {count}", preloadedKeys, {
-        en: "You have {count} invoices",
-      })
-    ).toThrow("[i18n] Key not preloaded: billing.invoice_summary (fr)");
-  });
-
-  it("rejects invalid ICU syntax", () => {
-    expect(() =>
-      assertPatchKeyMulti("default", "login_button", "en", "Sign {in", preloadedKeys, {
-        en: "Login",
-      })
-    ).toThrow("[i18n] ICU syntax error on patch:");
-  });
-
-  it("rejects incompatible ICU args against other locales for the same key", () => {
-    expect(() =>
-      assertPatchKeyMulti(
-        "billing",
-        "invoice_summary",
-        "en",
-        "{count, select, other {{count}}}",
-        preloadedKeys,
-        {
-          en: "You have {count, plural, one {1 invoice} other {{count} invoices}} for {name}",
-          it: "Hai {count, plural, one {1 fattura} other {{count} fatture}} per {name}",
-        }
-      )
-    ).toThrow("[i18n] ICU args mismatch on patch:");
-  });
-});

package/src/patch-key.ts

@@ -1,140 +0,0 @@
-import { mergeVariableMetaAcrossLocales, type VariableMetaSpec } from "./icu/extract-variables.js";
-import { parseTemplate } from "./icu/parse-template.js";
-import type { KeyDictionary, PartialKeyDictionary } from "./types.js";
-
-export function preloadKeySingle(key: string, locale: string): string {
-  return `${key}:${locale}`;
-}
-
-export function preloadKeyMulti(namespace: string, key: string, locale: string): string {
-  return `${namespace}:${key}:${locale}`;
-}
-
-export function seedPreloadedKeysSingle(
-  dictionary: KeyDictionary,
-  preloadedKeys: Set<string>
-): void {
-  for (const [key, localeByKey] of Object.entries(dictionary)) {
-    if (localeByKey === undefined || typeof localeByKey !== "object") {
-      continue;
-    }
-    for (const locale of Object.keys(localeByKey)) {
-      preloadedKeys.add(preloadKeySingle(key, locale));
-    }
-  }
-}
-
-export function seedPreloadedKeysMulti(
-  dictionary: Record<string, KeyDictionary>,
-  preloadedKeys: Set<string>
-): void {
-  for (const [namespace, keyDictionary] of Object.entries(dictionary)) {
-    if (keyDictionary === undefined || typeof keyDictionary !== "object") {
-      continue;
-    }
-    for (const [key, localeByKey] of Object.entries(keyDictionary)) {
-      if (localeByKey === undefined || typeof localeByKey !== "object") {
-        continue;
-      }
-      for (const locale of Object.keys(localeByKey)) {
-        preloadedKeys.add(preloadKeyMulti(namespace, key, locale));
-      }
-    }
-  }
-}
-
-export function recordPreloadedKeysSingle(
-  partial: PartialKeyDictionary<KeyDictionary, string>,
-  preloadedKeys: Set<string>
-): void {
-  for (const [key, incomingLocales] of Object.entries(partial)) {
-    if (incomingLocales === undefined || typeof incomingLocales !== "object") {
-      continue;
-    }
-    for (const locale of Object.keys(incomingLocales)) {
-      preloadedKeys.add(preloadKeySingle(key, locale));
-    }
-  }
-}
-
-export function recordPreloadedKeysMulti(
-  namespace: string,
-  partial: PartialKeyDictionary<KeyDictionary, string>,
-  preloadedKeys: Set<string>
-): void {
-  for (const [key, incomingLocales] of Object.entries(partial)) {
-    if (incomingLocales === undefined || typeof incomingLocales !== "object") {
-      continue;
-    }
-    for (const locale of Object.keys(incomingLocales)) {
-      preloadedKeys.add(preloadKeyMulti(namespace, key, locale));
-    }
-  }
-}
-
-function collectLocaleMetasForKey(
-  localeByKey: Record<string, string>,
-  patchedLocale: string,
-  patchedMeta: VariableMetaSpec
-): VariableMetaSpec[] {
-  const localeMetas: VariableMetaSpec[] = [patchedMeta];
-
-  for (const [locale, template] of Object.entries(localeByKey)) {
-    if (locale === patchedLocale) {
-      continue;
-    }
-    const parsed = parseTemplate(template);
-    if (parsed.ok) {
-      localeMetas.push(parsed.meta);
-    }
-  }
-
-  return localeMetas;
-}
-
-export function assertPatchKeySingle(
-  key: string,
-  locale: string,
-  template: string,
-  preloadedKeys: Set<string>,
-  localeByKey: Record<string, string> | undefined
-): void {
-  if (!preloadedKeys.has(preloadKeySingle(key, locale))) {
-    throw new Error(`[i18n] Key not preloaded: ${key} (${locale})`);
-  }
-
-  const parsed = parseTemplate(template);
-  if (!parsed.ok) {
-    throw new Error(`[i18n] ICU syntax error on patch: ${parsed.message}`);
-  }
-
-  const localeMetas = collectLocaleMetasForKey(localeByKey ?? {}, locale, parsed.meta);
-  const merged = mergeVariableMetaAcrossLocales(localeMetas);
-  if (!merged.ok) {
-    throw new Error(`[i18n] ICU args mismatch on patch: ${merged.message}`);
-  }
-}
-
-export function assertPatchKeyMulti(
-  namespace: string,
-  key: string,
-  locale: string,
-  template: string,
-  preloadedKeys: Set<string>,
-  localeByKey: Record<string, string> | undefined
-): void {
-  if (!preloadedKeys.has(preloadKeyMulti(namespace, key, locale))) {
-    throw new Error(`[i18n] Key not preloaded: ${namespace}.${key} (${locale})`);
-  }
-
-  const parsed = parseTemplate(template);
-  if (!parsed.ok) {
-    throw new Error(`[i18n] ICU syntax error on patch: ${parsed.message}`);
-  }
-
-  const localeMetas = collectLocaleMetasForKey(localeByKey ?? {}, locale, parsed.meta);
-  const merged = mergeVariableMetaAcrossLocales(localeMetas);
-  if (!merged.ok) {
-    throw new Error(`[i18n] ICU args mismatch on patch: ${merged.message}`);
-  }
-}