@xndrjs/i18n 0.7.0 → 0.8.0

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

@@ -0,0 +1,138 @@
+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

@@ -16,29 +16,9 @@ function formatVariableSpecObject(spec: VariableSpec): string {
 
 /** Builds the `DICTIONARY_SPEC` constant from ICU analysis output (keys + variable args). */
 export function formatDictionarySpecBlock(
-  isSingle: boolean,
   entries: NamespaceEntry[],
   argsSpecByNamespace: Record<string, Record<string, VariableSpec>>
 ): string {
-  if (isSingle) {
-    const onlyNamespace = entries[0]!.namespace;
-    const argsByKey = argsSpecByNamespace[onlyNamespace] ?? {};
-    const requiredKeys = Object.keys(argsByKey)
-      .map((key) => JSON.stringify(key))
-      .join(", ");
-    const argsLines = Object.entries(argsByKey)
-      .map(([key, spec]) => `    ${JSON.stringify(key)}: ${formatVariableSpecObject(spec)},`)
-      .join("\n");
-
-    return (
-      `export const DICTIONARY_SPEC = {\n` +
-      `  mode: 'single' as const,\n` +
-      `  requiredKeys: [${requiredKeys}] as const,\n` +
-      `  argsByKey: {\n${argsLines}\n  },\n` +
-      `} satisfies DictionarySpec;\n`
-    );
-  }
-
   const requiredKeysLines = entries
     .map((entry) => {
       const keys = Object.keys(argsSpecByNamespace[entry.namespace] ?? {})
@@ -69,34 +49,20 @@ export function formatDictionarySpecBlock(
 
 /**
  * Emits the optional dictionary-schema module: `DICTIONARY_SPEC` plus thin wrappers
- * around `@xndrjs/i18n/validation` for external dictionary ingestion.
+ * 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,
-  isSingle: boolean,
   dictionarySpecBlock: string,
   importExtension: ImportExtension
 ): string {
   const typesImport = toRelativeModuleImport(typesModule, importExtension);
-  const partialImport = isSingle
-    ? `  validateExternalDictionaryPartial as validateExternalDictionaryPartialCore,\n` +
-      `  validateExternalKey as validateExternalKeyCore,\n`
-    : `  validateExternalDictionaryPartial as validateExternalDictionaryPartialCore,\n` +
-      `  validateExternalNamespacePartial as validateExternalNamespacePartialCore,\n` +
-      `  validateExternalKey as validateExternalKeyCore,\n`;
-
-  const singleKeyValidator =
-    `export function validateExternalKey<K extends keyof ${schemaTypeName}>(\n` +
-    `  key: K,\n` +
-    `  input: unknown,\n` +
-    `): ValidationResult<Pick<${schemaTypeName}, K>> {\n` +
-    `  return validateExternalKeyCore<Pick<${schemaTypeName}, K>>(\n` +
-    `    key as string,\n` +
-    `    input,\n` +
-    `    DICTIONARY_SPEC,\n` +
-    `  );\n` +
-    `}\n\n`;
+  const partialImport =
+    `  validateExternalDictionaryPartial as validateExternalDictionaryPartialCore,\n` +
+    `  validateExternalNamespacePartial as validateExternalNamespacePartialCore,\n` +
+    `  validateExternalKey as validateExternalKeyCore,\n`;
 
   const multiValidators =
     `export function validateExternalNamespacePartial<NS extends keyof ${schemaTypeName}>(\n` +
@@ -125,8 +91,6 @@ export function formatDictionarySchemaFile(
     `  );\n` +
     `}\n\n`;
 
-  const keyValidator = isSingle ? singleKeyValidator : multiValidators;
-
   return (
     `${GENERATED_FILE_BANNER}` +
     `import {\n` +
@@ -144,6 +108,6 @@ export function formatDictionarySchemaFile(
     `    DICTIONARY_SPEC,\n` +
     `  );\n` +
     `}\n\n` +
-    keyValidator
+    multiValidators
   );
 }

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

@@ -3,9 +3,8 @@ import { formatInstanceFile, type InstanceFileOptions } from "./instance-file.js
 
 function baseOptions(overrides: Partial<InstanceFileOptions> = {}): InstanceFileOptions {
   return {
-    isSingle: false,
-    hasLazy: false,
     typesOutputPath: "src/i18n/i18n-types.generated.ts",
+    namespaceLoadersOutputPath: "src/i18n/namespace-loaders.generated.ts",
     paramsTypeName: "AppParams",
     schemaTypeName: "AppSchema",
     localeTypeName: "AppLocale",
@@ -13,9 +12,8 @@ function baseOptions(overrides: Partial<InstanceFileOptions> = {}): InstanceFile
     factoryName: "createI18n",
     hasLocaleFallback: true,
     hasLocaleType: true,
-    namespaceNames: ["default", "billing"],
     importExtension: "none",
-    delivery: "canonical",
+    delivery: "split-by-locale",
     ...overrides,
   };
 }
@@ -26,63 +24,48 @@ function packageImportBlock(output: string): string {
 }
 
 describe("formatInstanceFile package imports", () => {
-  it("emits only single-scope symbols for single eager projects", () => {
-    const imports = packageImportBlock(formatInstanceFile(baseOptions({ isSingle: true })));
-
-    expect(imports).toContain("IcuTranslationProviderSingle");
-    expect(imports).toContain("projectNamespaceLocalesCore");
-    expect(imports).toContain("type I18nScopeSingle");
-    expect(imports).toContain("type OnMissingTranslation");
-    expect(imports).not.toContain("createI18nBuilder");
-    expect(imports).not.toContain("createI18nMultiBuilder");
-    expect(imports).not.toContain("I18nBuilderMultiInitial");
-    expect(imports).not.toContain("I18nBuilderMultiOptions");
-    expect(imports).not.toContain("I18nBuilderMultiPartitioned");
-    expect(imports).not.toContain("I18nScopeMulti");
-    expect(imports).not.toContain("projectDictionaryLocalesCore");
-  });
-
-  it("emits multi eager scope symbols without builder imports", () => {
-    const imports = packageImportBlock(formatInstanceFile(baseOptions()));
+  it("emits lazy multi handle symbols", () => {
+    const output = formatInstanceFile(baseOptions());
+    const imports = packageImportBlock(output);
 
     expect(imports).toContain("IcuTranslationProviderMulti");
-    expect(imports).toContain("projectDictionaryLocalesCore");
-    expect(imports).toContain("type I18nScopeMulti");
-    expect(imports).not.toContain("createI18nMultiBuilder");
-    expect(imports).not.toContain("I18nBuilderMultiInitial");
-    expect(imports).not.toContain("I18nScopeSingle");
+    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("emits lazy multi builder symbols instead of I18nScopeMulti", () => {
-    const imports = packageImportBlock(
-      formatInstanceFile(
-        baseOptions({
-          hasLazy: true,
-          namespaceLoadersOutputPath: "src/i18n/namespace-loaders.generated.ts",
-        })
-      )
+  it("injects LOCALE_DELIVERY_AREA for custom delivery", () => {
+    const output = formatInstanceFile(
+      baseOptions({
+        delivery: "custom",
+        localeDeliveryAreaConstName: "LOCALE_DELIVERY_AREA",
+      })
     );
 
-    expect(imports).toContain("createI18nMultiBuilder");
-    expect(imports).toContain("type I18nBuilderMultiInitial");
-    expect(imports).toContain("type I18nBuilderMultiOptions");
-    expect(imports).not.toContain("type I18nScopeMulti");
-    expect(imports).not.toContain("createI18nBuilder");
-    expect(imports).not.toContain("I18nBuilderMultiPartitioned");
+    expect(output).toContain("LOCALE_DELIVERY_AREA");
+    expect(output).toContain("partitionForLocale: (locale) => LOCALE_DELIVERY_AREA[locale]");
   });
 
-  it("includes delivery-area projection helpers when delivery is custom", () => {
-    const imports = packageImportBlock(
-      formatInstanceFile(
-        baseOptions({
-          delivery: "custom",
-          deliveryAreaTypeName: "AppDeliveryArea",
-          deliveryArtifactsTypeName: "AppDeliveryArtifacts",
-        })
-      )
+  it("wires createNamespaceLoaders + required fetchImpl in options bag", () => {
+    const output = formatInstanceFile(
+      baseOptions({
+        loaderStrategy: "fetch",
+      })
     );
 
-    expect(imports).toContain("projectNamespaceForDeliveryAreaCore");
-    expect(imports).toContain("projectDictionaryForDeliveryAreaCore");
+    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 }");
   });
 });