@mandujs/core 0.53.3 → 0.54.0

package/src/i18n/message-registry.ts

@@ -1,173 +1,173 @@
-/**
- * Phase 18.μ — message registry + typed `t()` helper.
- *
- * `defineMessages()` creates a locale-keyed message bundle with its
- * keys inferred at compile time (via `as const`). `createTranslator()`
- * returns a `t(key, vars)` function bound to a specific active
- * locale — misses fall back to `fallbackLocale` then raw `key`.
- *
- * Placeholder syntax is Next.js / react-intl-lite compatible:
- * `"Hello, {{name}}!"` resolves `{ name: "Mandu" }` → `"Hello, Mandu!"`.
- * Missing vars are left as `{{name}}` so template errors are visible
- * in the rendered page instead of silently producing empty strings.
- */
-
-import type { LocaleCode, MessageBundle, Translator } from "./types";
-
-/**
- * Brand `defineMessages()` output so downstream helpers can verify
- * the caller actually went through the declared API. Runtime-only
- * field; TS infers it without the caller writing it.
- */
-export interface MessageRegistry<TKeys extends string = string> {
-  readonly __manduMessages: true;
-  readonly bundles: MessageBundle<TKeys>;
-  readonly locales: readonly LocaleCode[];
-  /**
-   * Look up a single message. Returns `undefined` when neither
-   * the requested locale nor the registry's configured fallbacks
-   * carry the key. The returned value is the raw template, NOT
-   * interpolated — use `createTranslator()` for the full pipeline.
-   */
-  lookup(locale: LocaleCode, key: TKeys, fallback?: LocaleCode): string | undefined;
-}
-
-/**
- * Create a message registry. The generic `TBundle` is inferred from
- * the argument when passed `as const`, giving `t()` compile-time
- * key checks.
- *
- * @example
- * ```ts
- * const messages = defineMessages({
- *   en: { welcome: "Welcome, {{name}}!" },
- *   ko: { welcome: "환영합니다, {{name}}님!" },
- * } as const);
- * ```
- */
-export function defineMessages<
-  TBundle extends Record<string, Record<string, string>>,
->(bundles: TBundle): MessageRegistry<
-  Extract<keyof TBundle[keyof TBundle], string>
-> {
-  if (!bundles || typeof bundles !== "object") {
-    throw new Error("[mandu/i18n] defineMessages() requires an object");
-  }
-  const locales = Object.keys(bundles);
-  if (locales.length === 0) {
-    throw new Error("[mandu/i18n] defineMessages() requires at least one locale");
-  }
-  for (const [locale, bundle] of Object.entries(bundles)) {
-    if (!bundle || typeof bundle !== "object") {
-      throw new Error(
-        `[mandu/i18n] defineMessages(): bundle for "${locale}" must be an object`
-      );
-    }
-    for (const [key, value] of Object.entries(bundle)) {
-      if (typeof value !== "string") {
-        throw new Error(
-          `[mandu/i18n] defineMessages(): "${locale}.${key}" must be a string`
-        );
-      }
-    }
-  }
-
-  type TKey = Extract<keyof TBundle[keyof TBundle], string>;
-
-  const registry: MessageRegistry<TKey> = {
-    __manduMessages: true,
-    bundles: bundles as unknown as MessageBundle<TKey>,
-    locales,
-    lookup(locale: LocaleCode, key: TKey, fallback?: LocaleCode): string | undefined {
-      const primary = (bundles as Record<string, Record<string, string>>)[locale]?.[key];
-      if (typeof primary === "string") return primary;
-      if (fallback && fallback !== locale) {
-        const alt = (bundles as Record<string, Record<string, string>>)[fallback]?.[key];
-        if (typeof alt === "string") return alt;
-      }
-      return undefined;
-    },
-  };
-  return registry;
-}
-
-/**
- * Replace `{{var}}` placeholders in `template` using `vars`. Missing
- * vars are preserved as `{{var}}` so templating bugs are visible in
- * the rendered output (not silently stripped). `vars[...]` values
- * that are numbers are coerced via `String(value)`.
- *
- * Whitespace inside braces is tolerated: `{{ name }}` and `{{name}}`
- * both resolve to `vars.name`.
- */
-export function interpolate(
-  template: string,
-  vars: Record<string, string | number> | undefined
-): string {
-  if (!vars) return template;
-  return template.replace(/\{\{\s*([A-Za-z0-9_]+)\s*\}\}/g, (match, key) => {
-    if (Object.prototype.hasOwnProperty.call(vars, key)) {
-      const value = vars[key as keyof typeof vars];
-      if (value === undefined || value === null) return match;
-      return String(value);
-    }
-    return match;
-  });
-}
-
-/**
- * Build a typed `t()` function bound to a specific active locale.
- * Misses walk `activeLocale → fallbackLocale → defaultLocale → key`
- * (skipping duplicates). The final fallback to raw `key` makes
- * missing-translation bugs highly visible during QA without
- * crashing the page.
- *
- * @example
- * ```ts
- * const messages = defineMessages({
- *   en: { greet: "Hi, {{name}}" },
- *   ko: { greet: "안녕, {{name}}" },
- * } as const);
- *
- * const t = createTranslator(messages, { activeLocale: "ko", defaultLocale: "en" });
- * t("greet", { name: "만두" }); // → "안녕, 만두"
- * ```
- */
-export function createTranslator<TKeys extends string>(
-  registry: MessageRegistry<TKeys>,
-  opts: {
-    activeLocale: LocaleCode;
-    defaultLocale: LocaleCode;
-    fallbackLocale?: LocaleCode;
-  }
-): Translator<TKeys> {
-  const { activeLocale, defaultLocale, fallbackLocale } = opts;
-  return function t(key, vars) {
-    const candidates: LocaleCode[] = [activeLocale];
-    if (fallbackLocale && !candidates.includes(fallbackLocale)) candidates.push(fallbackLocale);
-    if (!candidates.includes(defaultLocale)) candidates.push(defaultLocale);
-
-    for (const locale of candidates) {
-      const value = registry.lookup(locale, key as TKeys);
-      if (typeof value === "string") {
-        return interpolate(value, vars);
-      }
-    }
-    // Final fallback — raw key preserves "unresolved" signal instead
-    // of a blank string. `vars` is intentionally ignored here because
-    // the key itself isn't a template.
-    return key as unknown as string;
-  };
-}
-
-/**
- * Type guard for {@link MessageRegistry}. Useful when the runtime
- * receives `unknown` from user config (e.g. dynamic imports).
- */
-export function isMessageRegistry(value: unknown): value is MessageRegistry {
-  return (
-    typeof value === "object" &&
-    value !== null &&
-    (value as { __manduMessages?: unknown }).__manduMessages === true
-  );
-}
+/**
+ * Phase 18.μ — message registry + typed `t()` helper.
+ *
+ * `defineMessages()` creates a locale-keyed message bundle with its
+ * keys inferred at compile time (via `as const`). `createTranslator()`
+ * returns a `t(key, vars)` function bound to a specific active
+ * locale — misses fall back to `fallbackLocale` then raw `key`.
+ *
+ * Placeholder syntax is Next.js / react-intl-lite compatible:
+ * `"Hello, {{name}}!"` resolves `{ name: "Mandu" }` → `"Hello, Mandu!"`.
+ * Missing vars are left as `{{name}}` so template errors are visible
+ * in the rendered page instead of silently producing empty strings.
+ */
+
+import type { LocaleCode, MessageBundle, Translator } from "./types";
+
+/**
+ * Brand `defineMessages()` output so downstream helpers can verify
+ * the caller actually went through the declared API. Runtime-only
+ * field; TS infers it without the caller writing it.
+ */
+export interface MessageRegistry<TKeys extends string = string> {
+  readonly __manduMessages: true;
+  readonly bundles: MessageBundle<TKeys>;
+  readonly locales: readonly LocaleCode[];
+  /**
+   * Look up a single message. Returns `undefined` when neither
+   * the requested locale nor the registry's configured fallbacks
+   * carry the key. The returned value is the raw template, NOT
+   * interpolated — use `createTranslator()` for the full pipeline.
+   */
+  lookup(locale: LocaleCode, key: TKeys, fallback?: LocaleCode): string | undefined;
+}
+
+/**
+ * Create a message registry. The generic `TBundle` is inferred from
+ * the argument when passed `as const`, giving `t()` compile-time
+ * key checks.
+ *
+ * @example
+ * ```ts
+ * const messages = defineMessages({
+ *   en: { welcome: "Welcome, {{name}}!" },
+ *   ko: { welcome: "환영합니다, {{name}}님!" },
+ * } as const);
+ * ```
+ */
+export function defineMessages<
+  TBundle extends Record<string, Record<string, string>>,
+>(bundles: TBundle): MessageRegistry<
+  Extract<keyof TBundle[keyof TBundle], string>
+> {
+  if (!bundles || typeof bundles !== "object") {
+    throw new Error("[mandu/i18n] defineMessages() requires an object");
+  }
+  const locales = Object.keys(bundles);
+  if (locales.length === 0) {
+    throw new Error("[mandu/i18n] defineMessages() requires at least one locale");
+  }
+  for (const [locale, bundle] of Object.entries(bundles)) {
+    if (!bundle || typeof bundle !== "object") {
+      throw new Error(
+        `[mandu/i18n] defineMessages(): bundle for "${locale}" must be an object`
+      );
+    }
+    for (const [key, value] of Object.entries(bundle)) {
+      if (typeof value !== "string") {
+        throw new Error(
+          `[mandu/i18n] defineMessages(): "${locale}.${key}" must be a string`
+        );
+      }
+    }
+  }
+
+  type TKey = Extract<keyof TBundle[keyof TBundle], string>;
+
+  const registry: MessageRegistry<TKey> = {
+    __manduMessages: true,
+    bundles: bundles as unknown as MessageBundle<TKey>,
+    locales,
+    lookup(locale: LocaleCode, key: TKey, fallback?: LocaleCode): string | undefined {
+      const primary = (bundles as Record<string, Record<string, string>>)[locale]?.[key];
+      if (typeof primary === "string") return primary;
+      if (fallback && fallback !== locale) {
+        const alt = (bundles as Record<string, Record<string, string>>)[fallback]?.[key];
+        if (typeof alt === "string") return alt;
+      }
+      return undefined;
+    },
+  };
+  return registry;
+}
+
+/**
+ * Replace `{{var}}` placeholders in `template` using `vars`. Missing
+ * vars are preserved as `{{var}}` so templating bugs are visible in
+ * the rendered output (not silently stripped). `vars[...]` values
+ * that are numbers are coerced via `String(value)`.
+ *
+ * Whitespace inside braces is tolerated: `{{ name }}` and `{{name}}`
+ * both resolve to `vars.name`.
+ */
+export function interpolate(
+  template: string,
+  vars: Record<string, string | number> | undefined
+): string {
+  if (!vars) return template;
+  return template.replace(/\{\{\s*([A-Za-z0-9_]+)\s*\}\}/g, (match, key) => {
+    if (Object.prototype.hasOwnProperty.call(vars, key)) {
+      const value = vars[key as keyof typeof vars];
+      if (value === undefined || value === null) return match;
+      return String(value);
+    }
+    return match;
+  });
+}
+
+/**
+ * Build a typed `t()` function bound to a specific active locale.
+ * Misses walk `activeLocale → fallbackLocale → defaultLocale → key`
+ * (skipping duplicates). The final fallback to raw `key` makes
+ * missing-translation bugs highly visible during QA without
+ * crashing the page.
+ *
+ * @example
+ * ```ts
+ * const messages = defineMessages({
+ *   en: { greet: "Hi, {{name}}" },
+ *   ko: { greet: "안녕, {{name}}" },
+ * } as const);
+ *
+ * const t = createTranslator(messages, { activeLocale: "ko", defaultLocale: "en" });
+ * t("greet", { name: "만두" }); // → "안녕, 만두"
+ * ```
+ */
+export function createTranslator<TKeys extends string>(
+  registry: MessageRegistry<TKeys>,
+  opts: {
+    activeLocale: LocaleCode;
+    defaultLocale: LocaleCode;
+    fallbackLocale?: LocaleCode;
+  }
+): Translator<TKeys> {
+  const { activeLocale, defaultLocale, fallbackLocale } = opts;
+  return function t(key, vars) {
+    const candidates: LocaleCode[] = [activeLocale];
+    if (fallbackLocale && !candidates.includes(fallbackLocale)) candidates.push(fallbackLocale);
+    if (!candidates.includes(defaultLocale)) candidates.push(defaultLocale);
+
+    for (const locale of candidates) {
+      const value = registry.lookup(locale, key as TKeys);
+      if (typeof value === "string") {
+        return interpolate(value, vars);
+      }
+    }
+    // Final fallback — raw key preserves "unresolved" signal instead
+    // of a blank string. `vars` is intentionally ignored here because
+    // the key itself isn't a template.
+    return key as unknown as string;
+  };
+}
+
+/**
+ * Type guard for {@link MessageRegistry}. Useful when the runtime
+ * receives `unknown` from user config (e.g. dynamic imports).
+ */
+export function isMessageRegistry(value: unknown): value is MessageRegistry {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    (value as { __manduMessages?: unknown }).__manduMessages === true
+  );
+}

package/src/i18n/types.ts

@@ -1,112 +1,112 @@
-/**
- * Phase 18.μ — i18n types.
- *
- * Public type surface for Mandu's first-class i18n. Separated from
- * runtime so `import type` callers pay zero bundle cost.
- */
-
-/**
- * A locale code. The string is opaque to the framework — we never
- * parse it beyond "equality vs the configured allow-list", so
- * `"en"`, `"en-US"`, `"zh-Hant"`, `"ko-KR"`, `"pt-BR"` are all valid
- * and treated as distinct locales. Match case-sensitively to the
- * entries of `I18nConfig.locales`.
- */
-export type LocaleCode = string;
-
-/**
- * How the active locale is resolved from an incoming request.
- *
- * - `"path-prefix"` — Next.js default. `/en/docs` → `en`, `/ko/docs`
- *   → `ko`. Routes without a locale prefix fall through to
- *   `defaultLocale`. Path-prefix synthesis happens at manifest
- *   build time (see `router/fs-scanner.ts`).
- * - `"domain"` — locale-per-subdomain. `en.example.com` → `en`.
- *   The mapping is supplied via {@link I18nConfig.domains}.
- * - `"header"` — pure `Accept-Language` negotiation. Useful for
- *   APIs where URLs should stay locale-less.
- * - `"cookie"` — explicit user choice is stored in a cookie
- *   (default name: `mandu_locale`). Server-side persistence
- *   across navigations without URL mutation.
- */
-export type I18nStrategy = "path-prefix" | "domain" | "header" | "cookie";
-
-/**
- * Resolved locale state, attached to `ctx.locale` by the runtime
- * dispatcher. Carries the canonical `code`, the `strategy` that
- * produced it (for `Vary:` bookkeeping), and the raw `source` so
- * debuggers can see whether the URL won over the cookie.
- */
-export interface ResolvedLocale {
-  /** The resolved locale code (always one of `I18nConfig.locales`). */
-  code: LocaleCode;
-  /** Whether this request used the default locale (no explicit signal). */
-  isDefault: boolean;
-  /** Which strategy ultimately produced the locale. */
-  strategy: I18nStrategy | "default" | "fallback";
-  /** Raw input that produced the match, for debugging. */
-  source?: string;
-}
-
-/**
- * A map of translation strings keyed by locale. Typically declared
- * `as const` so keys are inferred literally and the `t()` helper can
- * reject typos at compile time.
- */
-export type MessageBundle<TKeys extends string = string> = {
-  [locale: string]: Record<TKeys, string>;
-};
-
-/**
- * Configuration for `defineI18n()`. Kept shallow so it round-trips
- * through JSON config files without loss.
- */
-export interface I18nConfig {
-  /**
-   * Non-empty allow-list of supported locales. First entry is NOT
-   * automatically the default — `defaultLocale` is explicit.
-   */
-  locales: readonly LocaleCode[];
-  /** Fallback when no resolver returns a known locale. MUST be in `locales`. */
-  defaultLocale: LocaleCode;
-  /**
-   * Optional fallback chain. When `t(key)` misses in the active
-   * locale, we look up `fallback` before `defaultLocale` before
-   * returning the raw key. Typical use: `{ defaultLocale: 'en',
-   * fallback: 'en-US' }` so `zh-Hant` falls through `en-US` to `en`.
-   */
-  fallback?: LocaleCode;
-  /** Locale detection strategy. See {@link I18nStrategy}. */
-  strategy: I18nStrategy;
-  /**
-   * Cookie name for `strategy: 'cookie'` OR a cookie override for
-   * any other strategy (useful for "user explicitly picked a
-   * locale" persistence). Default: `"mandu_locale"`.
-   */
-  cookieName?: string;
-  /**
-   * Domain → locale map for `strategy: 'domain'`. Required when
-   * `strategy === "domain"`; ignored otherwise.
-   */
-  domains?: Record<string, LocaleCode>;
-}
-
-/**
- * Result of `defineI18n()`. A frozen config object that downstream
- * resolver + registry use. The brand field prevents accidental
- * coercion from plain literals.
- */
-export interface I18nDefinition extends I18nConfig {
-  readonly __manduI18n: true;
-}
-
-/**
- * Strongly-typed translator. Given a registry whose entries
- * declared `as const`, `t()` rejects typos in `key`, and
- * `vars` accepts any `{{name}}` placeholders present in the
- * template.
- */
-export type Translator<TKeys extends string = string> = (
-  key: TKeys,
-  vars?: Record<string, string | number>
-) => string;
+/**
+ * Phase 18.μ — i18n types.
+ *
+ * Public type surface for Mandu's first-class i18n. Separated from
+ * runtime so `import type` callers pay zero bundle cost.
+ */
+
+/**
+ * A locale code. The string is opaque to the framework — we never
+ * parse it beyond "equality vs the configured allow-list", so
+ * `"en"`, `"en-US"`, `"zh-Hant"`, `"ko-KR"`, `"pt-BR"` are all valid
+ * and treated as distinct locales. Match case-sensitively to the
+ * entries of `I18nConfig.locales`.
+ */
+export type LocaleCode = string;
+
+/**
+ * How the active locale is resolved from an incoming request.
+ *
+ * - `"path-prefix"` — Next.js default. `/en/docs` → `en`, `/ko/docs`
+ *   → `ko`. Routes without a locale prefix fall through to
+ *   `defaultLocale`. Path-prefix synthesis happens at manifest
+ *   build time (see `router/fs-scanner.ts`).
+ * - `"domain"` — locale-per-subdomain. `en.example.com` → `en`.
+ *   The mapping is supplied via {@link I18nConfig.domains}.
+ * - `"header"` — pure `Accept-Language` negotiation. Useful for
+ *   APIs where URLs should stay locale-less.
+ * - `"cookie"` — explicit user choice is stored in a cookie
+ *   (default name: `mandu_locale`). Server-side persistence
+ *   across navigations without URL mutation.
+ */
+export type I18nStrategy = "path-prefix" | "domain" | "header" | "cookie";
+
+/**
+ * Resolved locale state, attached to `ctx.locale` by the runtime
+ * dispatcher. Carries the canonical `code`, the `strategy` that
+ * produced it (for `Vary:` bookkeeping), and the raw `source` so
+ * debuggers can see whether the URL won over the cookie.
+ */
+export interface ResolvedLocale {
+  /** The resolved locale code (always one of `I18nConfig.locales`). */
+  code: LocaleCode;
+  /** Whether this request used the default locale (no explicit signal). */
+  isDefault: boolean;
+  /** Which strategy ultimately produced the locale. */
+  strategy: I18nStrategy | "default" | "fallback";
+  /** Raw input that produced the match, for debugging. */
+  source?: string;
+}
+
+/**
+ * A map of translation strings keyed by locale. Typically declared
+ * `as const` so keys are inferred literally and the `t()` helper can
+ * reject typos at compile time.
+ */
+export type MessageBundle<TKeys extends string = string> = {
+  [locale: string]: Record<TKeys, string>;
+};
+
+/**
+ * Configuration for `defineI18n()`. Kept shallow so it round-trips
+ * through JSON config files without loss.
+ */
+export interface I18nConfig {
+  /**
+   * Non-empty allow-list of supported locales. First entry is NOT
+   * automatically the default — `defaultLocale` is explicit.
+   */
+  locales: readonly LocaleCode[];
+  /** Fallback when no resolver returns a known locale. MUST be in `locales`. */
+  defaultLocale: LocaleCode;
+  /**
+   * Optional fallback chain. When `t(key)` misses in the active
+   * locale, we look up `fallback` before `defaultLocale` before
+   * returning the raw key. Typical use: `{ defaultLocale: 'en',
+   * fallback: 'en-US' }` so `zh-Hant` falls through `en-US` to `en`.
+   */
+  fallback?: LocaleCode;
+  /** Locale detection strategy. See {@link I18nStrategy}. */
+  strategy: I18nStrategy;
+  /**
+   * Cookie name for `strategy: 'cookie'` OR a cookie override for
+   * any other strategy (useful for "user explicitly picked a
+   * locale" persistence). Default: `"mandu_locale"`.
+   */
+  cookieName?: string;
+  /**
+   * Domain → locale map for `strategy: 'domain'`. Required when
+   * `strategy === "domain"`; ignored otherwise.
+   */
+  domains?: Record<string, LocaleCode>;
+}
+
+/**
+ * Result of `defineI18n()`. A frozen config object that downstream
+ * resolver + registry use. The brand field prevents accidental
+ * coercion from plain literals.
+ */
+export interface I18nDefinition extends I18nConfig {
+  readonly __manduI18n: true;
+}
+
+/**
+ * Strongly-typed translator. Given a registry whose entries
+ * declared `as const`, `t()` rejects typos in `key`, and
+ * `vars` accepts any `{{name}}` placeholders present in the
+ * template.
+ */
+export type Translator<TKeys extends string = string> = (
+  key: TKeys,
+  vars?: Record<string, string | number>
+) => string;