@xndrjs/i18n 0.8.1 → 0.8.2-alpha.0

package/src/builder.test.ts

@@ -1,303 +0,0 @@
-import { describe, expect, expectTypeOf, it, vi } from "vitest";
-import { createI18nHandle } from "./builder.js";
-import { IcuTranslationProviderMulti } from "./IcuTranslationProviderMulti.js";
-
-type MultiSchema = {
-  default: {
-    login_button: { en: string; it: string };
-    welcome: { en: string };
-  };
-  billing: {
-    invoice_summary: { en: string; it: string };
-  };
-};
-
-type TestMultiParams = {
-  default: {
-    login_button: never;
-    welcome: { name: string };
-  };
-  billing: {
-    invoice_summary: { count: number; name: string };
-  };
-};
-
-const billingIt = {
-  invoice_summary: {
-    it: "Hai {count, plural, one {1 fattura} other {{count} fatture}} per {name}",
-  },
-};
-
-const billingEn = {
-  invoice_summary: {
-    en: "You have {count, plural, one {1 invoice} other {{count} invoices}} for {name}",
-  },
-};
-
-const defaultIt = {
-  login_button: { it: "Accedi" },
-  welcome: { it: "Benvenuto {name}!" },
-};
-
-describe("I18nHandle", () => {
-  it("load() invokes mock loaders, merges into the engine, and returns a bound view", async () => {
-    const billingLoader = vi.fn(async (locale: string) => {
-      return locale === "it" ? billingIt : billingEn;
-    });
-    const engine = new IcuTranslationProviderMulti<MultiSchema, TestMultiParams>({});
-    const handle = createI18nHandle(engine, {
-      namespaceLoaders: {
-        billing: billingLoader,
-      },
-    });
-
-    const view = await handle.load({ namespaces: ["billing"], locale: "it" });
-
-    expect(billingLoader).toHaveBeenCalledWith("it", { locale: "it" });
-    expect(view.locale).toBe("it");
-    expect(view.t("billing", "invoice_summary", { count: 2, name: "Ada" })).toBe(
-      "Hai 2 fatture per Ada"
-    );
-  });
-
-  it("loads multiple namespaces in one call", async () => {
-    const billingLoader = vi.fn(async (locale: string) =>
-      locale === "it" ? billingIt : billingEn
-    );
-    const defaultLoader = vi.fn(async () => defaultIt);
-    const engine = new IcuTranslationProviderMulti<MultiSchema, TestMultiParams>({});
-
-    const view = await createI18nHandle(engine, {
-      namespaceLoaders: {
-        billing: billingLoader,
-        default: defaultLoader,
-      },
-    }).load({ namespaces: ["billing", "default"], locale: "it" });
-
-    expect(billingLoader).toHaveBeenCalledWith("it", { locale: "it" });
-    expect(defaultLoader).toHaveBeenCalledWith("it", { locale: "it" });
-    expect(view.t("default", "login_button")).toBe("Accedi");
-    expect(view.t("billing", "invoice_summary", { count: 1, name: "Bob" })).toBe(
-      "Hai 1 fattura per Bob"
-    );
-  });
-
-  it("accumulates engine data across repeated load() calls on the same handle", async () => {
-    const billingLoader = vi.fn(async (locale: string) =>
-      locale === "it" ? billingIt : billingEn
-    );
-    const defaultLoader = vi.fn(async () => defaultIt);
-    const engine = new IcuTranslationProviderMulti<MultiSchema, TestMultiParams>({});
-    const handle = createI18nHandle(engine, {
-      namespaceLoaders: {
-        billing: billingLoader,
-        default: defaultLoader,
-      },
-    });
-
-    const billingView = await handle.load({ namespaces: ["billing"], locale: "it" });
-    const defaultView = await handle.load({ namespaces: ["default"], locale: "it" });
-
-    expect(billingLoader).toHaveBeenCalledTimes(1);
-    expect(defaultLoader).toHaveBeenCalledTimes(1);
-    expect(billingView.t("billing", "invoice_summary", { count: 1, name: "Ada" })).toBe(
-      "Hai 1 fattura per Ada"
-    );
-    expect(defaultView.t("default", "login_button")).toBe("Accedi");
-    expect(engine.getAll().billing?.invoice_summary?.it).toBe(billingIt.invoice_summary.it);
-    expect(engine.getAll().default?.login_button?.it).toBe("Accedi");
-  });
-
-  it("returns a view scoped to namespaces declared at load time", async () => {
-    const billingLoader = vi.fn(async (locale: string) =>
-      locale === "it" ? billingIt : billingEn
-    );
-    const defaultLoader = vi.fn(async () => defaultIt);
-    const engine = new IcuTranslationProviderMulti<MultiSchema, TestMultiParams>({});
-    const handle = createI18nHandle(engine, {
-      namespaceLoaders: {
-        billing: billingLoader,
-        default: defaultLoader,
-      },
-    });
-
-    const billingView = await handle.load({ namespaces: ["billing"], locale: "it" });
-    await handle.load({ namespaces: ["default"], locale: "it" });
-
-    expect(billingView.t("billing", "invoice_summary", { count: 1, name: "Ada" })).toBe(
-      "Hai 1 fattura per Ada"
-    );
-    // billingView is typed for the billing namespace only; default is excluded at compile time.
-  });
-
-  it("maps locale to delivery partition via partitionForLocale", async () => {
-    const billingLoader = vi.fn(async (area: string) => {
-      return area === "eu" ? billingIt : billingEn;
-    });
-    const engine = new IcuTranslationProviderMulti<MultiSchema, TestMultiParams>({});
-
-    const view = await createI18nHandle(engine, {
-      namespaceLoaders: {
-        billing: billingLoader,
-      },
-      partitionForLocale: (locale) => (locale === "it" ? "eu" : "us"),
-    }).load({ namespaces: ["billing"], locale: "it" });
-
-    expect(billingLoader).toHaveBeenCalledWith("eu", { locale: "it" });
-    expect(view.locale).toBe("it");
-    expect(view.t("billing", "invoice_summary", { count: 2, name: "Ada" })).toBe(
-      "Hai 2 fatture per Ada"
-    );
-    expectTypeOf(view.t).toBeCallableWith("billing", "invoice_summary", {
-      count: 2,
-      name: "Ada",
-    });
-  });
-
-  it("loads partitioned namespace loaders with locale", async () => {
-    const billingLoader = vi.fn(async (locale: string) =>
-      locale === "it"
-        ? {
-            invoice_summary: {
-              it: "Hai {count, plural, one {1 fattura} other {{count} fatture}} per {name}",
-            },
-          }
-        : {
-            invoice_summary: {
-              en: "You have {count, plural, one {1 invoice} other {{count} invoices}} for {name}",
-            },
-          }
-    );
-    const engine = new IcuTranslationProviderMulti<MultiSchema, TestMultiParams>({});
-
-    const view = await createI18nHandle(engine, {
-      namespaceLoaders: {
-        billing: billingLoader,
-      },
-    }).load({ namespaces: ["billing"], locale: "en" });
-
-    expect(billingLoader).toHaveBeenCalledTimes(1);
-    expect(billingLoader.mock.calls[0]).toEqual(["en", { locale: "en" }]);
-    expect(view.t("billing", "invoice_summary", { count: 1, name: "Ada" })).toBe(
-      "You have 1 invoice for Ada"
-    );
-  });
-
-  it("rejects an empty namespaces array", async () => {
-    const billingLoader = vi.fn(async () => billingEn);
-    const engine = new IcuTranslationProviderMulti<MultiSchema, TestMultiParams>({});
-    const handle = createI18nHandle(engine, {
-      namespaceLoaders: {
-        billing: billingLoader,
-      },
-    });
-
-    await expect(
-      handle.load({ namespaces: [] as unknown as ["billing"], locale: "en" })
-    ).rejects.toThrow("load() requires a non-empty namespaces array");
-  });
-
-  it("skips a repeated load for the same namespace partition", async () => {
-    const billingLoader = vi.fn(async (locale: string) =>
-      locale === "it" ? billingIt : billingEn
-    );
-    const engine = new IcuTranslationProviderMulti<MultiSchema, TestMultiParams>({});
-    const handle = createI18nHandle(engine, {
-      namespaceLoaders: { billing: billingLoader },
-    });
-
-    await handle.load({ namespaces: ["billing"], locale: "it" });
-    await handle.load({ namespaces: ["billing"], locale: "it" });
-
-    expect(billingLoader).toHaveBeenCalledTimes(1);
-  });
-
-  it("returns a destructuring-safe locale-bound scope from load()", async () => {
-    const billingLoader = vi.fn(async () => billingEn);
-    const engine = new IcuTranslationProviderMulti<MultiSchema, TestMultiParams>({});
-    const { t } = await createI18nHandle(engine, {
-      namespaceLoaders: { billing: billingLoader },
-    }).load({ namespaces: ["billing"], locale: "en" });
-
-    expect(t("billing", "invoice_summary", { count: 1, name: "Ada" })).toBe(
-      "You have 1 invoice for Ada"
-    );
-  });
-
-  it("still loads a different partition for the same namespace", async () => {
-    const billingLoader = vi.fn(async (locale: string) =>
-      locale === "it" ? billingIt : billingEn
-    );
-    const engine = new IcuTranslationProviderMulti<MultiSchema, TestMultiParams>({});
-    const handle = createI18nHandle(engine, {
-      namespaceLoaders: { billing: billingLoader },
-    });
-
-    await handle.load({ namespaces: ["billing"], locale: "it" });
-    await handle.load({ namespaces: ["billing"], locale: "en" });
-
-    expect(billingLoader).toHaveBeenCalledTimes(2);
-    expect(billingLoader).toHaveBeenNthCalledWith(1, "it", { locale: "it" });
-    expect(billingLoader).toHaveBeenNthCalledWith(2, "en", { locale: "en" });
-  });
-
-  it("peek() returns null until resources are loaded, then a sync scope", async () => {
-    const billingLoader = vi.fn(async () => billingEn);
-    const engine = new IcuTranslationProviderMulti<MultiSchema, TestMultiParams>({});
-    const handle = createI18nHandle(engine, {
-      namespaceLoaders: { billing: billingLoader },
-    });
-
-    expect(handle.peek({ namespaces: ["billing"], locale: "en" })).toBeNull();
-
-    await handle.load({ namespaces: ["billing"], locale: "en" });
-    const sync = handle.peek({ namespaces: ["billing"], locale: "en" });
-    expect(sync).not.toBeNull();
-    expect(sync!.t("billing", "invoice_summary", { count: 1, name: "Ada" })).toBe(
-      "You have 1 invoice for Ada"
-    );
-  });
-
-  it("getLoadState() tracks pending, loaded, and error resources", async () => {
-    let resolveBilling!: () => void;
-    const billingPending = new Promise<typeof billingEn>((resolve) => {
-      resolveBilling = () => resolve(billingEn);
-    });
-    const billingLoader = vi.fn(() => billingPending);
-    const failingLoader = vi.fn(async () => {
-      throw new Error("load failed");
-    });
-    const engine = new IcuTranslationProviderMulti<MultiSchema, TestMultiParams>({});
-    const handle = createI18nHandle(engine, {
-      namespaceLoaders: {
-        billing: billingLoader,
-        default: failingLoader,
-      },
-    });
-
-    expect(handle.getLoadState()).toEqual({ resources: [] });
-
-    const pending = handle.load({ namespaces: ["billing"], locale: "en" });
-    expect(handle.getLoadState()).toEqual({
-      resources: [{ namespace: "billing", partition: "en", status: "pending" }],
-    });
-
-    resolveBilling();
-    await pending;
-
-    expect(handle.getLoadState()).toEqual({
-      resources: [{ namespace: "billing", partition: "en", status: "loaded" }],
-    });
-
-    await expect(handle.load({ namespaces: ["default"], locale: "it" })).rejects.toThrow(
-      "load failed"
-    );
-
-    expect(handle.getLoadState()).toEqual({
-      resources: [
-        { namespace: "billing", partition: "en", status: "loaded" },
-        { namespace: "default", partition: "it", status: "error", error: expect.any(Error) },
-      ],
-    });
-  });
-});

package/src/builder.ts

@@ -1,15 +0,0 @@
-export type { NamespaceLoader, PartitionedLoader } from "./builder-loaders.js";
-export { invokeNamespaceLoader } from "./builder-loaders.js";
-export type {
-  I18nHandle,
-  I18nHandleOptions,
-  LoadNamespacesInput,
-  PartitionForLocale,
-  ScopeForLocale,
-} from "./i18n-handle.js";
-export { createI18nHandle } from "./i18n-handle.js";
-export type {
-  I18nLoadState,
-  I18nResourceLoadRecord,
-  I18nResourceLoadStatus,
-} from "./load-state.js";

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