@xndrjs/i18n 0.8.1 → 0.8.2-alpha.0

package/src/codegen/dictionary-spec-contract.ts

@@ -1,138 +0,0 @@
-import fs from "node:fs";
-import type { VariableSpec } from "../icu/extract-variables.js";
-import type { DictionarySpec } from "../validation/types.js";
-import type { NamespaceEntry } from "./types.js";
-
-/** Builds a multi-mode {@link DictionarySpec} from ICU analysis for the given entries. */
-export function buildDictionarySpecFromAnalysis(
-  entries: NamespaceEntry[],
-  argsSpecByNamespace: Record<string, Record<string, VariableSpec>>
-): Extract<DictionarySpec, { mode: "multi" }> {
-  const requiredKeys: Record<string, readonly string[]> = {};
-  const argsByKey: Record<string, Record<string, VariableSpec>> = {};
-
-  for (const entry of entries) {
-    const argsByKeyForNs = argsSpecByNamespace[entry.namespace] ?? {};
-    requiredKeys[entry.namespace] = Object.keys(argsByKeyForNs).sort();
-    argsByKey[entry.namespace] = argsByKeyForNs;
-  }
-
-  return {
-    mode: "multi",
-    requiredKeys,
-    argsByKey,
-  };
-}
-
-/**
- * Loads `DICTIONARY_SPEC` from a previously generated `dictionary-schema.generated.ts`.
- * Sync parse of the emitter format from {@link formatDictionarySpecBlock} (no TS runtime import).
- */
-export function loadDictionarySpecFromSchemaFile(
-  absoluteSchemaPath: string
-): Extract<DictionarySpec, { mode: "multi" }> {
-  if (!fs.existsSync(absoluteSchemaPath)) {
-    throw new Error(
-      `[Codegen Error] Missing dictionary schema at ${absoluteSchemaPath}. Run runCodegen first.`
-    );
-  }
-
-  const source = fs.readFileSync(absoluteSchemaPath, "utf8");
-  const match = source.match(
-    /export const DICTIONARY_SPEC = (\{[\s\S]*?\n\}) satisfies DictionarySpec;/
-  );
-  if (!match?.[1]) {
-    throw new Error(
-      `[Codegen Error] Could not parse DICTIONARY_SPEC from ${absoluteSchemaPath}. Re-run runCodegen.`
-    );
-  }
-
-  const cleaned = match[1].replace(/ as const/g, "");
-  let parsed: unknown;
-  try {
-    parsed = new Function(`"use strict"; return (${cleaned});`)();
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    throw new Error(
-      `[Codegen Error] Failed to evaluate DICTIONARY_SPEC from ${absoluteSchemaPath}: ${message}`
-    );
-  }
-
-  if (
-    !parsed ||
-    typeof parsed !== "object" ||
-    (parsed as DictionarySpec).mode !== "multi" ||
-    !("requiredKeys" in parsed) ||
-    !("argsByKey" in parsed)
-  ) {
-    throw new Error(
-      `[Codegen Error] DICTIONARY_SPEC in ${absoluteSchemaPath} is not a multi-mode DictionarySpec.`
-    );
-  }
-
-  return parsed as Extract<DictionarySpec, { mode: "multi" }>;
-}
-
-function sortedKeys(keys: readonly string[]): string[] {
-  return [...keys].sort();
-}
-
-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;
-  }
-  for (let i = 0; i < aKeys.length; i++) {
-    const key = aKeys[i]!;
-    if (key !== bKeys[i] || a[key] !== b[key]) {
-      return false;
-    }
-  }
-  return true;
-}
-
-function namespaceArgsEqual(
-  a: Readonly<Record<string, VariableSpec>> | undefined,
-  b: Readonly<Record<string, VariableSpec>> | undefined
-): boolean {
-  const aKeys = Object.keys(a ?? {}).sort();
-  const bKeys = Object.keys(b ?? {}).sort();
-  if (aKeys.length !== bKeys.length) {
-    return false;
-  }
-  for (const key of aKeys) {
-    if (!bKeys.includes(key)) {
-      return false;
-    }
-    if (!variableSpecsEqual(a![key]!, b![key]!)) {
-      return false;
-    }
-  }
-  return true;
-}
-
-/**
- * Returns true when `current` matches `established` for every namespace in `namespaces`
- * (same keys + same ICU VariableSpec per key).
- */
-export function namespaceContractsMatch(
-  namespaces: readonly string[],
-  current: Extract<DictionarySpec, { mode: "multi" }>,
-  established: Extract<DictionarySpec, { mode: "multi" }>
-): boolean {
-  for (const namespace of namespaces) {
-    const currentKeys = sortedKeys(current.requiredKeys[namespace] ?? []);
-    const establishedKeys = sortedKeys(established.requiredKeys[namespace] ?? []);
-    if (
-      currentKeys.length !== establishedKeys.length ||
-      currentKeys.some((key, index) => key !== establishedKeys[index])
-    ) {
-      return false;
-    }
-    if (!namespaceArgsEqual(current.argsByKey[namespace], established.argsByKey[namespace])) {
-      return false;
-    }
-  }
-  return true;
-}

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

@@ -1,113 +0,0 @@
-import type { VariableSpec } from "../../icu/extract-variables.js";
-import { GENERATED_FILE_BANNER, toRelativeModuleImport } from "../paths.js";
-import type { ImportExtension, NamespaceEntry } from "../types.js";
-
-function formatVariableSpecObject(spec: VariableSpec): string {
-  const entries = Object.entries(spec);
-  if (entries.length === 0) {
-    return "{}";
-  }
-
-  const lines = entries.map(
-    ([name, type]) => `      ${JSON.stringify(name)}: ${JSON.stringify(type)},`
-  );
-  return `{\n${lines.join("\n")}\n    }`;
-}
-
-/** Builds the `DICTIONARY_SPEC` constant from ICU analysis output (keys + variable args). */
-export function formatDictionarySpecBlock(
-  entries: NamespaceEntry[],
-  argsSpecByNamespace: Record<string, Record<string, VariableSpec>>
-): string {
-  const requiredKeysLines = entries
-    .map((entry) => {
-      const keys = Object.keys(argsSpecByNamespace[entry.namespace] ?? {})
-        .map((key) => JSON.stringify(key))
-        .join(", ");
-      return `    ${JSON.stringify(entry.namespace)}: [${keys}] as const,`;
-    })
-    .join("\n");
-
-  const argsByKeyLines = entries
-    .map((entry) => {
-      const argsByKey = argsSpecByNamespace[entry.namespace] ?? {};
-      const keyLines = Object.entries(argsByKey)
-        .map(([key, spec]) => `      ${JSON.stringify(key)}: ${formatVariableSpecObject(spec)},`)
-        .join("\n");
-      return `    ${JSON.stringify(entry.namespace)}: {\n${keyLines}\n    },`;
-    })
-    .join("\n");
-
-  return (
-    `export const DICTIONARY_SPEC = {\n` +
-    `  mode: 'multi' as const,\n` +
-    `  requiredKeys: {\n${requiredKeysLines}\n  },\n` +
-    `  argsByKey: {\n${argsByKeyLines}\n  },\n` +
-    `} satisfies DictionarySpec;\n`
-  );
-}
-
-/**
- * Emits the optional dictionary-schema module: `DICTIONARY_SPEC` plus thin wrappers
- * around `@xndrjs/i18n/validation` for validating external payloads before
- * updating authoring / `regenerateNamespaces` (e.g. CMS → authoring JSON), not for runtime key patches.
- */
-export function formatDictionarySchemaFile(
-  schemaTypeName: string,
-  typesModule: string,
-  dictionarySpecBlock: string,
-  importExtension: ImportExtension
-): string {
-  const typesImport = toRelativeModuleImport(typesModule, importExtension);
-  const partialImport =
-    `  validateExternalDictionaryPartial as validateExternalDictionaryPartialCore,\n` +
-    `  validateExternalNamespacePartial as validateExternalNamespacePartialCore,\n` +
-    `  validateExternalKey as validateExternalKeyCore,\n`;
-
-  const multiValidators =
-    `export function validateExternalNamespacePartial<NS extends keyof ${schemaTypeName}>(\n` +
-    `  namespace: NS,\n` +
-    `  input: unknown,\n` +
-    `): ValidationResult<Partial<${schemaTypeName}[NS]>> {\n` +
-    `  return validateExternalNamespacePartialCore<Partial<${schemaTypeName}[NS]>>(\n` +
-    `    namespace as string,\n` +
-    `    input,\n` +
-    `    DICTIONARY_SPEC,\n` +
-    `  );\n` +
-    `}\n\n` +
-    `export function validateExternalKey<\n` +
-    `  NS extends keyof ${schemaTypeName},\n` +
-    `  K extends keyof ${schemaTypeName}[NS],\n` +
-    `>(\n` +
-    `  namespace: NS,\n` +
-    `  key: K,\n` +
-    `  input: unknown,\n` +
-    `): ValidationResult<Pick<${schemaTypeName}[NS], K>> {\n` +
-    `  return validateExternalKeyCore<Pick<${schemaTypeName}[NS], K>>(\n` +
-    `    namespace as string,\n` +
-    `    key as string,\n` +
-    `    input,\n` +
-    `    DICTIONARY_SPEC,\n` +
-    `  );\n` +
-    `}\n\n`;
-
-  return (
-    `${GENERATED_FILE_BANNER}` +
-    `import {\n` +
-    partialImport +
-    `  type DictionarySpec,\n` +
-    `  type ValidationResult,\n` +
-    `} from '@xndrjs/i18n/validation';\n` +
-    `import type { ${schemaTypeName} } from '${typesImport}';\n\n` +
-    `${dictionarySpecBlock}\n` +
-    `export function validateExternalDictionaryPartial(\n` +
-    `  input: unknown,\n` +
-    `): ValidationResult<Partial<${schemaTypeName}>> {\n` +
-    `  return validateExternalDictionaryPartialCore<Partial<${schemaTypeName}>>(\n` +
-    `    input,\n` +
-    `    DICTIONARY_SPEC,\n` +
-    `  );\n` +
-    `}\n\n` +
-    multiValidators
-  );
-}

package/src/codegen/emit/instance-file.test.ts

@@ -1,71 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { formatInstanceFile, type InstanceFileOptions } from "./instance-file.js";
-
-function baseOptions(overrides: Partial<InstanceFileOptions> = {}): InstanceFileOptions {
-  return {
-    typesOutputPath: "src/i18n/i18n-types.generated.ts",
-    namespaceLoadersOutputPath: "src/i18n/namespace-loaders.generated.ts",
-    paramsTypeName: "AppParams",
-    schemaTypeName: "AppSchema",
-    localeTypeName: "AppLocale",
-    localeFallbackConstName: "LOCALE_FALLBACK",
-    factoryName: "createI18n",
-    hasLocaleFallback: true,
-    hasLocaleType: true,
-    importExtension: "none",
-    delivery: "split-by-locale",
-    ...overrides,
-  };
-}
-
-function packageImportBlock(output: string): string {
-  const match = output.match(/import \{([\s\S]*?)\} from '@xndrjs\/i18n'/);
-  return match?.[1] ?? "";
-}
-
-describe("formatInstanceFile package imports", () => {
-  it("emits lazy multi handle symbols", () => {
-    const output = formatInstanceFile(baseOptions());
-    const imports = packageImportBlock(output);
-
-    expect(imports).toContain("IcuTranslationProviderMulti");
-    expect(imports).toContain("createI18nHandle");
-    expect(imports).toContain("type I18nHandle");
-    expect(imports).toContain("type I18nHandleOptions");
-    expect(output).toContain("partitionForLocale: (locale) => locale");
-    expect(output).toContain("I18nHandle<AppSchema, AppParams, AppLocale>");
-    expect(output).toContain(
-      "options?: { state?: { dictionary: InitialSchema; resources?: readonly (readonly [string, string])[] }; onMissing?: OnMissingTranslation }"
-    );
-    expect(output).toContain("const { state, ...providerOptions } = options ?? {}");
-  });
-
-  it("injects LOCALE_DELIVERY_AREA for custom delivery", () => {
-    const output = formatInstanceFile(
-      baseOptions({
-        delivery: "custom",
-        localeDeliveryAreaConstName: "LOCALE_DELIVERY_AREA",
-      })
-    );
-
-    expect(output).toContain("LOCALE_DELIVERY_AREA");
-    expect(output).toContain("partitionForLocale: (locale) => LOCALE_DELIVERY_AREA[locale]");
-  });
-
-  it("wires createNamespaceLoaders + required fetchImpl in options bag", () => {
-    const output = formatInstanceFile(
-      baseOptions({
-        loaderStrategy: "fetch",
-      })
-    );
-
-    expect(output).toContain("type FetchArtifact");
-    expect(output).toContain("import { createNamespaceLoaders }");
-    expect(output).toContain(
-      "options: { fetchImpl: FetchArtifact; state?: { dictionary: InitialSchema; resources?: readonly (readonly [string, string])[] }; onMissing?: OnMissingTranslation }"
-    );
-    expect(output).toContain("const { fetchImpl, state, ...providerOptions } = options;");
-    expect(output).toContain("createNamespaceLoaders(fetchImpl)");
-    expect(output).not.toContain("import { namespaceLoaders }");
-  });
-});

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

@@ -1,257 +0,0 @@
-import { GENERATED_FILE_BANNER, toModuleBasename, toRelativeModuleImport } from "../paths.js";
-import type { DeliveryMode, LoaderStrategy } from "../codegen-config-schema.js";
-import type { ImportExtension } from "../types.js";
-
-/** Emits the generated instance module: `createI18n` factory wrapping the ICU provider. */
-export interface InstanceFileOptions {
-  typesOutputPath: string;
-  namespaceLoadersOutputPath: string;
-  paramsTypeName: string;
-  schemaTypeName: string;
-  localeTypeName: string;
-  localeFallbackConstName: string;
-  factoryName: string;
-  hasLocaleFallback: boolean;
-  hasLocaleType: boolean;
-  importExtension: ImportExtension;
-  delivery: DeliveryMode;
-  localeDeliveryAreaConstName?: string;
-  loaderStrategy?: LoaderStrategy;
-}
-
-const STATE_TYPE = `{ dictionary: InitialSchema; resources?: readonly (readonly [string, string])[] }`;
-
-export function formatInstanceFile(options: InstanceFileOptions): string {
-  const {
-    typesOutputPath,
-    namespaceLoadersOutputPath,
-    paramsTypeName,
-    schemaTypeName,
-    localeTypeName,
-    localeFallbackConstName,
-    factoryName,
-    hasLocaleFallback,
-    hasLocaleType,
-    importExtension,
-    delivery,
-    localeDeliveryAreaConstName = "LOCALE_DELIVERY_AREA",
-    loaderStrategy = "import",
-  } = options;
-
-  const providerClass = "IcuTranslationProviderMulti";
-  const typesModule = toModuleBasename(typesOutputPath);
-  const typesImport = toRelativeModuleImport(typesModule, importExtension);
-  const loadersModule = toModuleBasename(namespaceLoadersOutputPath);
-  const loadersImport = toRelativeModuleImport(loadersModule, importExtension);
-  const schemaTypesImport = `import type { ${paramsTypeName}, ${schemaTypeName}, InitialSchema } from '${typesImport}';\n`;
-  const typesImportLine = formatTypesValueImport({
-    hasLocaleType,
-    hasLocaleFallback,
-    localeTypeName,
-    localeFallbackConstName,
-    localeDeliveryAreaConstName,
-    delivery,
-    typesImport,
-  });
-  const packageImports = formatPackageImports(providerClass, loaderStrategy);
-  const loadersImportLine =
-    loaderStrategy === "fetch"
-      ? `import { createNamespaceLoaders } from '${loadersImport}';\n`
-      : `import { namespaceLoaders } from '${loadersImport}';\n`;
-
-  const createFactoryBlock = formatCreateI18nFactory({
-    providerClass,
-    schemaTypeName,
-    paramsTypeName,
-    localeTypeName,
-    localeFallbackConstName,
-    factoryName,
-    hasLocaleFallback,
-    delivery,
-    localeDeliveryAreaConstName,
-    loaderStrategy,
-  });
-
-  return (
-    `${GENERATED_FILE_BANNER}` +
-    `import {\n` +
-    `  ${packageImports},\n` +
-    `} from '@xndrjs/i18n';\n` +
-    schemaTypesImport +
-    typesImportLine +
-    loadersImportLine +
-    `\n` +
-    createFactoryBlock
-  );
-}
-
-function formatTypesValueImport(options: {
-  hasLocaleType: boolean;
-  hasLocaleFallback: boolean;
-  localeTypeName: string;
-  localeFallbackConstName: string;
-  localeDeliveryAreaConstName: string;
-  delivery: DeliveryMode;
-  typesImport: string;
-}): string {
-  const {
-    hasLocaleType,
-    hasLocaleFallback,
-    localeTypeName,
-    localeFallbackConstName,
-    localeDeliveryAreaConstName,
-    delivery,
-    typesImport,
-  } = options;
-
-  if (!hasLocaleType && delivery !== "custom") {
-    return "";
-  }
-
-  const valueNames: string[] = [];
-  if (hasLocaleFallback) {
-    valueNames.push(localeFallbackConstName);
-  }
-  if (delivery === "custom") {
-    valueNames.push(localeDeliveryAreaConstName);
-  }
-
-  if (valueNames.length > 0 && hasLocaleType) {
-    return `import { ${valueNames.join(", ")}, type ${localeTypeName} } from '${typesImport}';\n`;
-  }
-  if (valueNames.length > 0) {
-    return `import { ${valueNames.join(", ")} } from '${typesImport}';\n`;
-  }
-  if (hasLocaleType) {
-    return `import type { ${localeTypeName} } from '${typesImport}';\n`;
-  }
-  return "";
-}
-
-function formatCreateI18nFactory(options: {
-  providerClass: string;
-  schemaTypeName: string;
-  paramsTypeName: string;
-  localeTypeName: string;
-  localeFallbackConstName: string;
-  factoryName: string;
-  hasLocaleFallback: boolean;
-  delivery: DeliveryMode;
-  localeDeliveryAreaConstName: string;
-  loaderStrategy: LoaderStrategy;
-}): string {
-  const {
-    providerClass,
-    schemaTypeName,
-    paramsTypeName,
-    localeTypeName,
-    localeFallbackConstName,
-    factoryName,
-    hasLocaleFallback,
-    delivery,
-    localeDeliveryAreaConstName,
-    loaderStrategy,
-  } = options;
-
-  const providerTypeArgs = hasLocaleFallback
-    ? `${schemaTypeName}, ${paramsTypeName}, ${localeTypeName}, typeof ${localeFallbackConstName}`
-    : `${schemaTypeName}, ${paramsTypeName}`;
-  const handleReturnType = `I18nHandle<${schemaTypeName}, ${paramsTypeName}, ${localeTypeName}>`;
-  const handleTypeArgs = `<${schemaTypeName}, ${paramsTypeName}, ${localeTypeName}>`;
-
-  const partitionForLocale =
-    delivery === "custom"
-      ? `    partitionForLocale: (locale) => ${localeDeliveryAreaConstName}[locale],\n`
-      : `    partitionForLocale: (locale) => locale,\n`;
-
-  const optionsType =
-    loaderStrategy === "fetch"
-      ? `{ fetchImpl: FetchArtifact; state?: ${STATE_TYPE}; onMissing?: OnMissingTranslation }`
-      : `{ state?: ${STATE_TYPE}; onMissing?: OnMissingTranslation }`;
-
-  const optionsParam =
-    loaderStrategy === "fetch" ? `  options: ${optionsType},\n` : `  options?: ${optionsType},\n`;
-
-  const namespaceLoadersLine =
-    loaderStrategy === "fetch"
-      ? `    namespaceLoaders: createNamespaceLoaders(fetchImpl),\n`
-      : `    namespaceLoaders,\n`;
-
-  return (
-    `export function ${factoryName}(\n` +
-    optionsParam +
-    `): ${handleReturnType} {\n` +
-    formatBody({
-      providerClass,
-      providerTypeArgs,
-      hasLocaleFallback,
-      localeFallbackConstName,
-      loaderStrategy,
-    }) +
-    `  engine.seedBuilderResources(normalized.resources);\n` +
-    `  return createI18nHandle${handleTypeArgs}(engine, {\n` +
-    namespaceLoadersLine +
-    partitionForLocale +
-    `  } as I18nHandleOptions<${schemaTypeName}, ${localeTypeName}>);\n` +
-    `}\n`
-  );
-}
-
-function formatBody(options: {
-  providerClass: string;
-  providerTypeArgs: string;
-  hasLocaleFallback: boolean;
-  localeFallbackConstName: string;
-  loaderStrategy: LoaderStrategy;
-}): string {
-  const {
-    providerClass,
-    providerTypeArgs,
-    hasLocaleFallback,
-    localeFallbackConstName,
-    loaderStrategy,
-  } = options;
-
-  if (loaderStrategy === "fetch") {
-    const engineBlock = hasLocaleFallback
-      ? `  const engine = new ${providerClass}<${providerTypeArgs}>(normalized.dictionary, {\n` +
-        `    localeFallback: ${localeFallbackConstName},\n` +
-        `    ...providerOptions,\n` +
-        `  });\n`
-      : `  const engine = new ${providerClass}<${providerTypeArgs}>(normalized.dictionary, providerOptions);\n`;
-
-    return (
-      `  const { fetchImpl, state, ...providerOptions } = options;\n` +
-      `  const normalized = normalizeI18nCreateInput(state);\n` +
-      engineBlock
-    );
-  }
-
-  const engineBlock = hasLocaleFallback
-    ? `  const engine = new ${providerClass}<${providerTypeArgs}>(normalized.dictionary, {\n` +
-      `    localeFallback: ${localeFallbackConstName},\n` +
-      `    ...providerOptions,\n` +
-      `  });\n`
-    : `  const engine = new ${providerClass}<${providerTypeArgs}>(normalized.dictionary, providerOptions);\n`;
-
-  return (
-    `  const { state, ...providerOptions } = options ?? {};\n` +
-    `  const normalized = normalizeI18nCreateInput(state);\n` +
-    engineBlock
-  );
-}
-
-function formatPackageImports(providerClass: string, loaderStrategy: LoaderStrategy): string {
-  const names = [
-    providerClass,
-    "createI18nHandle",
-    "normalizeI18nCreateInput",
-    "type I18nHandle",
-    "type I18nHandleOptions",
-    "type OnMissingTranslation",
-  ];
-  if (loaderStrategy === "fetch") {
-    names.push("type FetchArtifact");
-  }
-  return names.join(",\n  ");
-}