@xndrjs/i18n 0.8.0 → 0.8.2-alpha.0

package/src/codegen/codegen-config-schema.ts

@@ -1,156 +0,0 @@
-import { z } from "zod";
-import path from "node:path";
-import { IDENTIFIER_NAME_PATTERN, IDENTIFIER_NAME_REQUIREMENT } from "./constants.js";
-import { getDeliveryArtifactsStructureIssues } from "./delivery-artifacts.js";
-import { typeNamesForProject } from "../codegen-config/type-names.js";
-
-const localeFallbackSchema = z.record(z.string(), z.union([z.string(), z.null()]));
-const deliveryArtifactsSchema = z.record(z.string(), z.array(z.string().min(1)));
-
-export const DELIVERY_MODES = ["split-by-locale", "custom"] as const;
-export type DeliveryMode = (typeof DELIVERY_MODES)[number];
-
-export const LOADER_STRATEGIES = ["import", "fetch"] as const;
-export type LoaderStrategy = (typeof LOADER_STRATEGIES)[number];
-
-const PROJECT_NAME_PATTERN = /^[A-Z][a-zA-Z0-9]*$/;
-
-const codegenConfigShape = {
-  /** PascalCase project id — generates `{project}Params`, `{project}Schema`, `{project}Locale`. */
-  projectName: z
-    .string()
-    .min(1)
-    .regex(PROJECT_NAME_PATTERN, 'projectName must be PascalCase (e.g. "MyApp")'),
-  namespaces: z.record(z.string(), z.string().min(1)),
-  /**
-   * Directory for generated TypeScript modules:
-   * `i18n-types.generated.ts`, `instance.generated.ts`,
-   * `namespace-loaders.generated.ts`, `dictionary-schema.generated.ts`.
-   */
-  codegenPath: z.string().min(1),
-  localeFallback: localeFallbackSchema.optional(),
-  delivery: z.enum(DELIVERY_MODES).optional().default("split-by-locale"),
-  deliveryArtifacts: deliveryArtifactsSchema.optional(),
-  /** Directory for delivery JSON (`translations/`). Defaults to {@link codegenPath}. */
-  artifactsPath: z.string().min(1).optional(),
-  /**
-   * How generated `namespaceLoaders` resolve artifacts.
-   * - `import` (default): dynamic `import()` — JSON is bundled; content updates need a rebuild.
-   * - `fetch`: runtime `fetchImpl({ locale, namespace, area? })` via required `createI18n({ fetchImpl })`.
-   *   Codegen does not know URLs — mapping id → transport is an application concern.
-   */
-  loaderStrategy: z.enum(LOADER_STRATEGIES).optional().default("import"),
-};
-
-export const codegenConfigKeys = Object.keys(
-  codegenConfigShape
-) as (keyof typeof codegenConfigShape)[];
-
-export const codegenConfigSchema = z
-  .object(codegenConfigShape)
-  .strict()
-  .superRefine((config, ctx) => {
-    for (const namespace of Object.keys(config.namespaces)) {
-      if (!IDENTIFIER_NAME_PATTERN.test(namespace)) {
-        ctx.addIssue({
-          code: "custom",
-          path: ["namespaces", namespace],
-          message: `Invalid namespace name "${namespace}" (${IDENTIFIER_NAME_REQUIREMENT}).`,
-        });
-      }
-    }
-
-    if (config.delivery === "custom") {
-      if (!config.deliveryArtifacts) {
-        ctx.addIssue({
-          code: "custom",
-          path: ["deliveryArtifacts"],
-          message: 'deliveryArtifacts is required when delivery is "custom".',
-        });
-      } else {
-        for (const issue of getDeliveryArtifactsStructureIssues(config.deliveryArtifacts)) {
-          ctx.addIssue({
-            code: "custom",
-            path: issue.path,
-            message: issue.message,
-          });
-        }
-      }
-    } else if (config.deliveryArtifacts !== undefined) {
-      ctx.addIssue({
-        code: "custom",
-        path: ["deliveryArtifacts"],
-        message: 'deliveryArtifacts is only allowed when delivery is "custom".',
-      });
-    }
-  });
-
-export type CodegenConfigInput = z.input<typeof codegenConfigSchema>;
-export type CodegenConfig = z.infer<typeof codegenConfigSchema>;
-
-export const GENERATED_BASENAMES = {
-  types: "i18n-types.generated.ts",
-  instance: "instance.generated.ts",
-  namespaceLoaders: "namespace-loaders.generated.ts",
-  dictionarySchema: "dictionary-schema.generated.ts",
-} as const;
-
-export const DEFAULT_FACTORY_NAME = "createI18n";
-export const DEFAULT_LOCALE_FALLBACK_CONST_NAME = "LOCALE_FALLBACK";
-
-/** Derived paths and symbol names from `projectName` + `codegenPath`. */
-export interface ResolvedCodegenPaths {
-  codegenPath: string;
-  typesOutput: string;
-  instanceOutput: string;
-  namespaceLoadersOutput: string;
-  dictionarySchemaOutput: string;
-  artifactsPath: string;
-  paramsTypeName: string;
-  schemaTypeName: string;
-  localeTypeName: string;
-  localeFallbackConstName: string;
-  factoryName: string;
-  deliveryAreaTypeName: string;
-}
-
-export function resolveCodegenPaths(
-  config: Pick<CodegenConfig, "projectName" | "codegenPath" | "artifactsPath">
-): ResolvedCodegenPaths {
-  const typeNames = typeNamesForProject(config.projectName);
-  const codegenPath = config.codegenPath;
-  return {
-    codegenPath,
-    typesOutput: path.join(codegenPath, GENERATED_BASENAMES.types),
-    instanceOutput: path.join(codegenPath, GENERATED_BASENAMES.instance),
-    namespaceLoadersOutput: path.join(codegenPath, GENERATED_BASENAMES.namespaceLoaders),
-    dictionarySchemaOutput: path.join(codegenPath, GENERATED_BASENAMES.dictionarySchema),
-    artifactsPath: config.artifactsPath ?? codegenPath,
-    paramsTypeName: typeNames.paramsTypeName,
-    schemaTypeName: typeNames.schemaTypeName,
-    localeTypeName: typeNames.localeTypeName,
-    localeFallbackConstName: DEFAULT_LOCALE_FALLBACK_CONST_NAME,
-    factoryName: DEFAULT_FACTORY_NAME,
-    deliveryAreaTypeName: `${config.projectName}DeliveryArea`,
-  };
-}
-
-export function resolveArtifactsPath(
-  config: Pick<CodegenConfig, "codegenPath" | "artifactsPath">
-): string {
-  return config.artifactsPath ?? config.codegenPath;
-}
-
-export function formatCodegenConfigIssues(error: z.ZodError): string {
-  const issueLines = error.issues.map((issue) => {
-    const path = issue.path.length > 0 ? issue.path.join(".") : "(root)";
-    return `  - ${path}: ${issue.message}`;
-  });
-
-  return [
-    "[Codegen Error] Invalid i18n.codegen.json:",
-    ...issueLines,
-    "",
-    `Allowed keys: ${codegenConfigKeys.join(", ")}`,
-  ].join("\n");
-}

package/src/codegen/config.test.ts

@@ -1,231 +0,0 @@
-import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import { afterEach, describe, expect, it } from "vitest";
-import { codegenConfigKeys, resolveCodegenPaths } from "./codegen-config-schema.js";
-import { loadConfig, resolveArtifactsPath } from "./config.js";
-
-function writeConfig(dir: string, config: Record<string, unknown>) {
-  const configPath = join(dir, "i18n.codegen.json");
-  writeFileSync(configPath, JSON.stringify(config, null, 2));
-  return configPath;
-}
-
-const validMultiConfig = {
-  projectName: "App",
-  namespaces: {
-    default: "translations/default.json",
-  },
-  codegenPath: "generated",
-};
-
-describe("loadConfig", () => {
-  let tempDir: string;
-
-  afterEach(() => {
-    if (tempDir) {
-      rmSync(tempDir, { recursive: true, force: true });
-    }
-  });
-
-  it("accepts a valid multi-namespace config and defaults delivery to split-by-locale", () => {
-    tempDir = mkdtempSync(join(tmpdir(), "xndrjs-i18n-config-"));
-    const configPath = writeConfig(tempDir, validMultiConfig);
-
-    expect(loadConfig(configPath)).toEqual({
-      ...validMultiConfig,
-      delivery: "split-by-locale",
-      loaderStrategy: "import",
-    });
-  });
-
-  it("accepts fetch loaderStrategy", () => {
-    tempDir = mkdtempSync(join(tmpdir(), "xndrjs-i18n-config-"));
-    const configPath = writeConfig(tempDir, {
-      ...validMultiConfig,
-      loaderStrategy: "fetch",
-    });
-
-    expect(loadConfig(configPath)).toMatchObject({
-      loaderStrategy: "fetch",
-    });
-  });
-
-  it("rejects unknown config keys", () => {
-    tempDir = mkdtempSync(join(tmpdir(), "xndrjs-i18n-config-"));
-    const configPath = writeConfig(tempDir, {
-      ...validMultiConfig,
-      notARealKey: true,
-    });
-
-    expect(() => loadConfig(configPath)).toThrow();
-  });
-
-  it("resolves code paths and type names from projectName + codegenPath", () => {
-    expect(resolveCodegenPaths(validMultiConfig)).toMatchObject({
-      typesOutput: "generated/i18n-types.generated.ts",
-      instanceOutput: "generated/instance.generated.ts",
-      namespaceLoadersOutput: "generated/namespace-loaders.generated.ts",
-      dictionarySchemaOutput: "generated/dictionary-schema.generated.ts",
-      artifactsPath: "generated",
-      paramsTypeName: "AppParams",
-      schemaTypeName: "AppSchema",
-      localeTypeName: "AppLocale",
-      factoryName: "createI18n",
-      localeFallbackConstName: "LOCALE_FALLBACK",
-    });
-  });
-
-  it("throws on invalid config JSON", () => {
-    tempDir = mkdtempSync(join(tmpdir(), "xndrjs-i18n-config-"));
-    const configPath = join(tempDir, "i18n.codegen.json");
-    writeFileSync(configPath, "{ not json");
-
-    expect(() => loadConfig(configPath)).toThrow(
-      `[Codegen Error] Failed to parse config JSON (${configPath})`
-    );
-  });
-
-  it("throws on unknown top-level keys and reports allowed keys", () => {
-    tempDir = mkdtempSync(join(tmpdir(), "xndrjs-i18n-config-"));
-    const configPath = writeConfig(tempDir, {
-      ...validMultiConfig,
-      typoKey: true,
-    });
-
-    const act = () => loadConfig(configPath);
-    expect(act).toThrow("Invalid i18n.codegen.json");
-    expect(act).toThrow("typoKey");
-    expect(act).toThrow(`Allowed keys: ${codegenConfigKeys.join(", ")}`);
-  });
-
-  it("throws when required fields are missing", () => {
-    tempDir = mkdtempSync(join(tmpdir(), "xndrjs-i18n-config-"));
-    const configPath = writeConfig(tempDir, {
-      namespaces: validMultiConfig.namespaces,
-    });
-
-    const act = () => loadConfig(configPath);
-    expect(act).toThrow("projectName");
-    expect(act).toThrow("codegenPath");
-    expect(act).toThrow("Allowed keys:");
-  });
-
-  it("throws when projectName is not PascalCase", () => {
-    tempDir = mkdtempSync(join(tmpdir(), "xndrjs-i18n-config-"));
-    const configPath = writeConfig(tempDir, {
-      ...validMultiConfig,
-      projectName: "my-app",
-    });
-
-    expect(() => loadConfig(configPath)).toThrow("projectName must be PascalCase");
-  });
-
-  it("throws when a namespace name is not a valid identifier", () => {
-    tempDir = mkdtempSync(join(tmpdir(), "xndrjs-i18n-config-"));
-    const configPath = writeConfig(tempDir, {
-      ...validMultiConfig,
-      namespaces: {
-        default: "translations/default.json",
-        "user-area": "translations/user-area.json",
-      },
-    });
-
-    expect(() => loadConfig(configPath)).toThrow(
-      'Invalid namespace name "user-area" (allowed: letters, digits, underscore; must not start with a digit).'
-    );
-  });
-
-  it("accepts artifactsPath for custom json artifact directory", () => {
-    tempDir = mkdtempSync(join(tmpdir(), "xndrjs-i18n-config-"));
-    const configPath = writeConfig(tempDir, {
-      ...validMultiConfig,
-      artifactsPath: "public/i18n",
-    });
-
-    expect(loadConfig(configPath)).toMatchObject({
-      artifactsPath: "public/i18n",
-      delivery: "split-by-locale",
-    });
-  });
-
-  it("resolveArtifactsPath defaults to codegenPath", () => {
-    expect(
-      resolveArtifactsPath({
-        codegenPath: "generated",
-      })
-    ).toBe("generated");
-    expect(
-      resolveArtifactsPath({
-        codegenPath: "generated",
-        artifactsPath: "public/i18n",
-      })
-    ).toBe("public/i18n");
-  });
-
-  it("accepts custom delivery with deliveryArtifacts", () => {
-    tempDir = mkdtempSync(join(tmpdir(), "xndrjs-i18n-config-"));
-    const configPath = writeConfig(tempDir, {
-      ...validMultiConfig,
-      delivery: "custom",
-      deliveryArtifacts: {
-        eu: ["it", "fr"],
-        us: ["en-US"],
-      },
-      localeFallback: {
-        "en-US": null,
-        it: "en-US",
-        fr: null,
-      },
-    });
-
-    expect(loadConfig(configPath)).toMatchObject({
-      delivery: "custom",
-      deliveryArtifacts: {
-        eu: ["it", "fr"],
-        us: ["en-US"],
-      },
-    });
-  });
-
-  it("throws when delivery is custom without deliveryArtifacts", () => {
-    tempDir = mkdtempSync(join(tmpdir(), "xndrjs-i18n-config-"));
-    const configPath = writeConfig(tempDir, {
-      ...validMultiConfig,
-      delivery: "custom",
-    });
-
-    expect(() => loadConfig(configPath)).toThrow(
-      'deliveryArtifacts is required when delivery is "custom"'
-    );
-  });
-
-  it("throws when deliveryArtifacts is set for non-custom delivery", () => {
-    tempDir = mkdtempSync(join(tmpdir(), "xndrjs-i18n-config-"));
-    const configPath = writeConfig(tempDir, {
-      ...validMultiConfig,
-      delivery: "split-by-locale",
-      deliveryArtifacts: {
-        eu: ["it"],
-      },
-    });
-
-    expect(() => loadConfig(configPath)).toThrow(
-      'deliveryArtifacts is only allowed when delivery is "custom"'
-    );
-  });
-
-  it("throws when deliveryArtifacts has duplicate locales across areas", () => {
-    tempDir = mkdtempSync(join(tmpdir(), "xndrjs-i18n-config-"));
-    const configPath = writeConfig(tempDir, {
-      ...validMultiConfig,
-      delivery: "custom",
-      deliveryArtifacts: {
-        eu: ["it", "fr"],
-        us: ["fr"],
-      },
-    });
-
-    expect(() => loadConfig(configPath)).toThrow('Locale "fr" appears in both "eu" and "us"');
-  });
-});

package/src/codegen/config.ts

@@ -1,42 +0,0 @@
-import fs from "node:fs";
-import type { NamespaceEntry } from "./types.js";
-import {
-  CodegenConfig,
-  codegenConfigSchema,
-  formatCodegenConfigIssues,
-} from "./codegen-config-schema.js";
-
-export {
-  resolveCodegenPaths,
-  resolveArtifactsPath,
-  GENERATED_BASENAMES,
-  DEFAULT_FACTORY_NAME,
-  DEFAULT_LOCALE_FALLBACK_CONST_NAME,
-} from "./codegen-config-schema.js";
-
-/** Parses and validates `i18n.codegen.json`; first step of the codegen pipeline. */
-export function loadConfig(configPath: string): CodegenConfig {
-  let raw: unknown;
-
-  try {
-    raw = JSON.parse(fs.readFileSync(configPath, "utf8"));
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    throw new Error(`[Codegen Error] Failed to parse config JSON (${configPath}): ${message}`);
-  }
-
-  const result = codegenConfigSchema.safeParse(raw);
-  if (!result.success) {
-    throw new Error(formatCodegenConfigIssues(result.error));
-  }
-
-  return result.data;
-}
-
-/** Maps config namespaces to namespace entries. */
-export function resolveNamespaces(config: CodegenConfig): NamespaceEntry[] {
-  return Object.entries(config.namespaces).map(([namespace, filePath]) => ({
-    namespace,
-    filePath,
-  }));
-}

package/src/codegen/constants.ts

@@ -1,9 +0,0 @@
-export const SUPPORTED_IMPORT_EXTENSIONS = ["none", ".ts", ".js"] as const;
-export type SupportedImportExtension = (typeof SUPPORTED_IMPORT_EXTENSIONS)[number];
-
-// Translation keys and namespace names become TypeScript identifiers and
-// template-literal type segments in the generated code, so they must be valid
-// identifiers (e.g. "app.title" would emit the broken type `"app.title:..."`).
-export const IDENTIFIER_NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
-export const IDENTIFIER_NAME_REQUIREMENT =
-  "allowed: letters, digits, underscore; must not start with a digit";

package/src/codegen/delivery-artifacts.test.ts

@@ -1,167 +0,0 @@
-import { describe, expect, it } from "vitest";
-import {
-  formatDeliveryArtifactsBlock,
-  formatLocaleDeliveryAreaBlock,
-  getDeliveryAreaNames,
-  getDeliveryArtifactsIssues,
-  getDeliveryArtifactsPartitionIssues,
-  getDeliveryArtifactsStructureIssues,
-  getDeliveryArtifactsTypeName,
-  getLocaleDeliveryAreaMap,
-} from "./delivery-artifacts.js";
-
-describe("delivery-artifacts", () => {
-  const validArtifacts = {
-    eu: ["it", "fr"],
-    us: ["en-US"],
-  };
-
-  it("accepts a valid structure", () => {
-    expect(getDeliveryArtifactsStructureIssues(validArtifacts)).toEqual([]);
-  });
-
-  it("rejects invalid area names", () => {
-    const issues = getDeliveryArtifactsStructureIssues({
-      "1eu": ["it"],
-    });
-
-    expect(issues).toHaveLength(1);
-    expect(issues[0]?.message).toContain('Invalid delivery area name "1eu"');
-  });
-
-  it("rejects empty area locale lists", () => {
-    const issues = getDeliveryArtifactsStructureIssues({
-      eu: [],
-      us: ["en-US"],
-    });
-
-    expect(issues).toHaveLength(1);
-    expect(issues[0]?.message).toContain('Delivery area "eu" must include at least one locale');
-  });
-
-  it("rejects duplicate locales across areas", () => {
-    const issues = getDeliveryArtifactsStructureIssues({
-      eu: ["it", "fr"],
-      us: ["fr", "en-US"],
-    });
-
-    expect(issues).toHaveLength(1);
-    expect(issues[0]?.message).toContain('Locale "fr" appears in both "eu" and "us"');
-  });
-
-  it("requires an exhaustive partition of request locales", () => {
-    const requestLocales = new Set(["it", "fr", "en-US"]);
-
-    expect(getDeliveryArtifactsPartitionIssues(validArtifacts, requestLocales)).toEqual([]);
-  });
-
-  it("reports missing request locales", () => {
-    const issues = getDeliveryArtifactsPartitionIssues(
-      { eu: ["it"] },
-      new Set(["it", "fr", "en-US"])
-    );
-
-    expect(issues).toHaveLength(1);
-    expect(issues[0]?.message).toContain("missing locales");
-    expect(issues[0]?.message).toContain("fr");
-    expect(issues[0]?.message).toContain("en-US");
-  });
-
-  it("reports excess locales not in request set", () => {
-    const issues = getDeliveryArtifactsPartitionIssues(validArtifacts, new Set(["it"]));
-
-    expect(issues).toHaveLength(1);
-    expect(issues[0]?.message).toContain("includes locales not required");
-    expect(issues[0]?.message).toContain("fr");
-    expect(issues[0]?.message).toContain("en-US");
-  });
-
-  it("getDeliveryArtifactsIssues merges structure and partition errors", () => {
-    const issues = getDeliveryArtifactsIssues(
-      {
-        eu: [],
-        "1bad": ["it"],
-        us: ["it"],
-      },
-      new Set(["it", "en-US"])
-    );
-
-    expect(issues.map((issue) => issue.message)).toEqual(
-      expect.arrayContaining([
-        expect.stringContaining('Delivery area "eu" must include at least one locale'),
-        expect.stringContaining('Invalid delivery area name "1bad"'),
-        expect.stringContaining('Locale "it" appears in both "1bad" and "us"'),
-        expect.stringContaining("missing locales"),
-        expect.stringContaining("en-US"),
-      ])
-    );
-  });
-
-  it("returns sorted delivery area names", () => {
-    expect(
-      getDeliveryAreaNames({
-        us: ["en-US"],
-        eu: ["it", "fr"],
-      })
-    ).toEqual(["eu", "us"]);
-  });
-
-  it("builds locale to delivery area map", () => {
-    expect(
-      getLocaleDeliveryAreaMap({
-        amer: ["en-US", "es-AR"],
-        eu: ["en", "it", "fr", "es"],
-      })
-    ).toEqual({
-      en: "eu",
-      "en-US": "amer",
-      "es-AR": "amer",
-      es: "eu",
-      fr: "eu",
-      it: "eu",
-    });
-  });
-
-  it("formats locale delivery area block for generated types", () => {
-    expect(
-      formatLocaleDeliveryAreaBlock(
-        {
-          eu: ["it", "fr"],
-          us: ["en-US"],
-        },
-        "LOCALE_DELIVERY_AREA",
-        "AppLocale",
-        "AppDeliveryArea"
-      )
-    ).toBe(
-      "export const LOCALE_DELIVERY_AREA = {\n" +
-        '  "en-US": "us",\n' +
-        '  "fr": "eu",\n' +
-        '  "it": "eu",\n' +
-        "} as const satisfies Record<AppLocale, AppDeliveryArea>;\n\n"
-    );
-  });
-
-  it("formats delivery artifacts block for generated types", () => {
-    expect(getDeliveryArtifactsTypeName("AppDeliveryArea")).toBe("AppDeliveryArtifacts");
-
-    expect(
-      formatDeliveryArtifactsBlock(
-        {
-          eu: ["it", "fr"],
-          us: ["en-US"],
-        },
-        "DELIVERY_ARTIFACTS",
-        "AppLocale",
-        "AppDeliveryArea"
-      )
-    ).toBe(
-      "export const DELIVERY_ARTIFACTS = {\n" +
-        '  "eu": ["fr", "it"] as const,\n' +
-        '  "us": ["en-US"] as const,\n' +
-        "} as const satisfies Record<AppDeliveryArea, readonly AppLocale[]>;\n\n" +
-        "export type AppDeliveryArtifacts = typeof DELIVERY_ARTIFACTS;\n\n" +
-        "export type LocalesForDeliveryArea<A extends AppDeliveryArea> = AppDeliveryArtifacts[A][number];\n\n"
-    );
-  });
-});