@xndrjs/i18n 0.8.0 → 0.8.2-alpha.0

package/src/codegen/delivery-artifacts.ts

@@ -1,154 +0,0 @@
-/** Valid TypeScript identifier / filename segment for a delivery area id. */
-export const DELIVERY_AREA_NAME_PATTERN = /^[a-zA-Z][a-zA-Z0-9_-]*$/;
-
-export type DeliveryArtifactsMap = Record<string, readonly string[]>;
-
-export type DeliveryArtifactsIssue = {
-  path: (string | number)[];
-  message: string;
-};
-
-export function getDeliveryArtifactsStructureIssues(
-  deliveryArtifacts: DeliveryArtifactsMap
-): DeliveryArtifactsIssue[] {
-  const issues: DeliveryArtifactsIssue[] = [];
-
-  for (const [area, locales] of Object.entries(deliveryArtifacts)) {
-    if (!DELIVERY_AREA_NAME_PATTERN.test(area)) {
-      issues.push({
-        path: ["deliveryArtifacts", area],
-        message: `Invalid delivery area name "${area}": must match ${DELIVERY_AREA_NAME_PATTERN.source}`,
-      });
-    }
-
-    if (locales.length === 0) {
-      issues.push({
-        path: ["deliveryArtifacts", area],
-        message: `Delivery area "${area}" must include at least one locale.`,
-      });
-    }
-  }
-
-  const localeToArea = new Map<string, string>();
-  for (const [area, locales] of Object.entries(deliveryArtifacts)) {
-    for (const locale of locales) {
-      const previousArea = localeToArea.get(locale);
-      if (previousArea) {
-        issues.push({
-          path: ["deliveryArtifacts", area],
-          message: `Locale "${locale}" appears in both "${previousArea}" and "${area}".`,
-        });
-      } else {
-        localeToArea.set(locale, area);
-      }
-    }
-  }
-
-  return issues;
-}
-
-export function getDeliveryArtifactsPartitionIssues(
-  deliveryArtifacts: DeliveryArtifactsMap,
-  requestLocales: ReadonlySet<string>
-): DeliveryArtifactsIssue[] {
-  const issues: DeliveryArtifactsIssue[] = [];
-  const artifactLocales = new Set<string>();
-
-  for (const locales of Object.values(deliveryArtifacts)) {
-    for (const locale of locales) {
-      artifactLocales.add(locale);
-    }
-  }
-
-  const missing = [...requestLocales].filter((locale) => !artifactLocales.has(locale)).sort();
-  if (missing.length > 0) {
-    issues.push({
-      path: ["deliveryArtifacts"],
-      message: `deliveryArtifacts is missing locales required by dictionaries and localeFallback: ${missing.join(", ")}`,
-    });
-  }
-
-  const excess = [...artifactLocales].filter((locale) => !requestLocales.has(locale)).sort();
-  if (excess.length > 0) {
-    issues.push({
-      path: ["deliveryArtifacts"],
-      message: `deliveryArtifacts includes locales not required by dictionaries and localeFallback: ${excess.join(", ")}`,
-    });
-  }
-
-  return issues;
-}
-
-/** Pre-emit validation gate for `deliveryArtifacts` in custom delivery mode. */
-export function getDeliveryArtifactsIssues(
-  deliveryArtifacts: DeliveryArtifactsMap,
-  requestLocales: ReadonlySet<string>
-): DeliveryArtifactsIssue[] {
-  return [
-    ...getDeliveryArtifactsStructureIssues(deliveryArtifacts),
-    ...getDeliveryArtifactsPartitionIssues(deliveryArtifacts, requestLocales),
-  ];
-}
-
-export function getDeliveryAreaNames(deliveryArtifacts: DeliveryArtifactsMap): string[] {
-  return Object.keys(deliveryArtifacts).sort();
-}
-
-export function getLocaleDeliveryAreaMap(
-  deliveryArtifacts: DeliveryArtifactsMap
-): Record<string, string> {
-  const localeToArea: Record<string, string> = {};
-
-  for (const [area, locales] of Object.entries(deliveryArtifacts)) {
-    for (const locale of locales) {
-      localeToArea[locale] = area;
-    }
-  }
-
-  return localeToArea;
-}
-
-export function formatLocaleDeliveryAreaBlock(
-  deliveryArtifacts: DeliveryArtifactsMap,
-  constName: string,
-  localeTypeName: string,
-  deliveryAreaTypeName: string
-): string {
-  const localeToArea = getLocaleDeliveryAreaMap(deliveryArtifacts);
-  const lines = Object.keys(localeToArea)
-    .sort()
-    .map((locale) => `  ${JSON.stringify(locale)}: ${JSON.stringify(localeToArea[locale])},`)
-    .join("\n");
-
-  return `export const ${constName} = {\n${lines}\n} as const satisfies Record<${localeTypeName}, ${deliveryAreaTypeName}>;\n\n`;
-}
-
-export function getDeliveryArtifactsTypeName(deliveryAreaTypeName: string): string {
-  return deliveryAreaTypeName.endsWith("DeliveryArea")
-    ? deliveryAreaTypeName.replace(/DeliveryArea$/, "DeliveryArtifacts")
-    : `${deliveryAreaTypeName}Artifacts`;
-}
-
-export function formatDeliveryArtifactsBlock(
-  deliveryArtifacts: DeliveryArtifactsMap,
-  constName: string,
-  localeTypeName: string,
-  deliveryAreaTypeName: string
-): string {
-  const deliveryArtifactsTypeName = getDeliveryArtifactsTypeName(deliveryAreaTypeName);
-  const areaEntries = getDeliveryAreaNames(deliveryArtifacts)
-    .map((area) => {
-      const locales = [...deliveryArtifacts[area]!]
-        .sort()
-        .map((locale) => JSON.stringify(locale))
-        .join(", ");
-      return `  ${JSON.stringify(area)}: [${locales}] as const,`;
-    })
-    .join("\n");
-
-  return (
-    `export const ${constName} = {\n${areaEntries}\n} as const satisfies Record<${deliveryAreaTypeName}, readonly ${localeTypeName}[]>;\n\n` +
-    `export type ${deliveryArtifactsTypeName} = typeof ${constName};\n\n` +
-    `export type LocalesForDeliveryArea<A extends ${deliveryAreaTypeName}> = ${deliveryArtifactsTypeName}[A][number];\n\n`
-  );
-}

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

@@ -1,28 +0,0 @@
-import { describe, expect, it } from "vitest";
-import {
-  buildDictionarySpecFromAnalysis,
-  namespaceContractsMatch,
-} from "./dictionary-spec-contract.js";
-
-describe("dictionary-spec-contract", () => {
-  it("namespaceContractsMatch compares keys and VariableSpec", () => {
-    const entries = [{ namespace: "default", filePath: "translations/default.json" }];
-    const current = buildDictionarySpecFromAnalysis(entries, {
-      default: { welcome: { name: "string" }, login: {} },
-    });
-    const established = buildDictionarySpecFromAnalysis(entries, {
-      default: { welcome: { name: "string" }, login: {} },
-    });
-    expect(namespaceContractsMatch(["default"], current, established)).toBe(true);
-
-    const changedArgs = buildDictionarySpecFromAnalysis(entries, {
-      default: { welcome: { name: "string", extra: "string" }, login: {} },
-    });
-    expect(namespaceContractsMatch(["default"], changedArgs, established)).toBe(false);
-
-    const changedKeys = buildDictionarySpecFromAnalysis(entries, {
-      default: { welcome: { name: "string" } },
-    });
-    expect(namespaceContractsMatch(["default"], changedKeys, established)).toBe(false);
-  });
-});

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 }");
-  });
-});