@mandujs/core 0.30.0 → 0.32.0

package/src/i18n/locale-resolver.ts

@@ -0,0 +1,214 @@
+/**
+ * Phase 18.μ — locale resolution.
+ *
+ * Given a request + i18n config, return the active {@link ResolvedLocale}.
+ * Resolution order depends on `config.strategy`:
+ *
+ *   path-prefix → URL path segment → cookie → Accept-Language → default
+ *   domain      → Host header      → cookie → Accept-Language → default
+ *   header      → Accept-Language  → cookie → default
+ *   cookie      → Cookie           → Accept-Language → default
+ *
+ * In every mode, an invalid locale signal (e.g. `/fr/docs` when `fr`
+ * isn't configured) falls through to the next signal — invalid inputs
+ * never short-circuit to an error. The final tier is always the
+ * configured `defaultLocale` or `fallback`.
+ *
+ * This module is pure; it never touches the server registry or
+ * `ctx.cookies`. Callers assemble the result and bolt it onto the
+ * request via `ManduContext` — see `runtime/server.ts` μ dispatch
+ * section.
+ */
+
+import type { I18nDefinition, LocaleCode, ResolvedLocale } from "./types";
+import { DEFAULT_I18N_COOKIE } from "./define";
+
+/**
+ * Remove a locale prefix from a URL pathname. Returns `{ locale, rest }`
+ * when the pathname starts with `/<locale>(/...)?` for a known locale;
+ * otherwise `{ locale: undefined, rest: pathname }`.
+ *
+ * Handles trailing + empty slashes so `/en`, `/en/`, `/en/docs` all
+ * match `locale="en"` with the rest normalized to `"/"`, `"/"`, `"/docs"`.
+ */
+export function stripLocalePrefix(
+  pathname: string,
+  locales: readonly LocaleCode[]
+): { locale: LocaleCode | undefined; rest: string } {
+  if (!pathname.startsWith("/")) {
+    return { locale: undefined, rest: pathname };
+  }
+  // Fast path: root.
+  if (pathname === "/") return { locale: undefined, rest: "/" };
+  const slashIdx = pathname.indexOf("/", 1);
+  const first = slashIdx === -1 ? pathname.slice(1) : pathname.slice(1, slashIdx);
+  if (!locales.includes(first)) {
+    return { locale: undefined, rest: pathname };
+  }
+  const rest = slashIdx === -1 ? "/" : pathname.slice(slashIdx);
+  return { locale: first, rest };
+}
+
+/**
+ * Parse the `Accept-Language` header and pick the best supported
+ * locale. Honours q-weights; falls back to undefined when nothing
+ * matches.
+ *
+ * Comparison is case-insensitive, and we accept exact-match only
+ * (no Accept-Language `en-US` → `en` widening — userland can list
+ * both in `config.locales` when they want fallback behaviour).
+ */
+export function parseAcceptLanguage(
+  header: string | null | undefined,
+  locales: readonly LocaleCode[]
+): LocaleCode | undefined {
+  if (!header) return undefined;
+  const want = new Map<string, number>();
+  for (const piece of header.split(",")) {
+    const [tagRaw, ...params] = piece.trim().split(";");
+    if (!tagRaw) continue;
+    const tag = tagRaw.trim().toLowerCase();
+    if (!tag || tag === "*") continue;
+    let q = 1.0;
+    for (const p of params) {
+      const m = /^\s*q\s*=\s*([0-9.]+)\s*$/i.exec(p);
+      if (m) q = parseFloat(m[1]!);
+    }
+    if (Number.isFinite(q) && q > 0 && !want.has(tag)) {
+      want.set(tag, q);
+    }
+  }
+  // Highest-q first; stable within equal weights.
+  const sorted = [...want.entries()].sort((a, b) => b[1] - a[1]);
+  const lowerLocales = locales.map((l) => ({ raw: l, lower: l.toLowerCase() }));
+  for (const [tag] of sorted) {
+    for (const { raw, lower } of lowerLocales) {
+      if (lower === tag) return raw;
+    }
+  }
+  // Widening fallback: `zh-TW` → try `zh` if only `zh` is configured.
+  for (const [tag] of sorted) {
+    const short = tag.split("-")[0]!;
+    for (const { raw, lower } of lowerLocales) {
+      if (lower === short) return raw;
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Read the locale cookie from the raw `Cookie` header. A nano-parser
+ * so the resolver stays dependency-free (the `CookieManager` in
+ * `filling/context.ts` lives on the request-wrapping side, not here).
+ */
+export function readLocaleCookie(
+  header: string | null | undefined,
+  cookieName: string,
+  locales: readonly LocaleCode[]
+): LocaleCode | undefined {
+  if (!header) return undefined;
+  const target = `${cookieName}=`;
+  for (const piece of header.split(";")) {
+    const trimmed = piece.trim();
+    if (!trimmed.startsWith(target)) continue;
+    const raw = trimmed.slice(target.length);
+    try {
+      const value = decodeURIComponent(raw);
+      if (locales.includes(value)) return value;
+    } catch {
+      // fallthrough
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Resolve the locale for this request.
+ *
+ * The returned {@link ResolvedLocale} is always valid w.r.t.
+ * `config.locales` — when every signal misses, we fall back to
+ * `fallback` then `defaultLocale` (in that order) and flag the
+ * result with `strategy: "fallback"` / `"default"`.
+ */
+export function resolveLocale(
+  request: Request,
+  config: I18nDefinition
+): ResolvedLocale {
+  const url = new URL(request.url);
+  const cookieName = config.cookieName ?? DEFAULT_I18N_COOKIE;
+  const cookieHeader = request.headers.get("cookie");
+  const acceptLanguage = request.headers.get("accept-language");
+
+  switch (config.strategy) {
+    case "path-prefix": {
+      const { locale } = stripLocalePrefix(url.pathname, config.locales);
+      if (locale) {
+        return { code: locale, isDefault: false, strategy: "path-prefix", source: url.pathname };
+      }
+      const cookie = readLocaleCookie(cookieHeader, cookieName, config.locales);
+      if (cookie) {
+        return { code: cookie, isDefault: false, strategy: "cookie", source: cookieHeader ?? undefined };
+      }
+      const accept = parseAcceptLanguage(acceptLanguage, config.locales);
+      if (accept) {
+        return { code: accept, isDefault: false, strategy: "header", source: acceptLanguage ?? undefined };
+      }
+      return finalFallback(config);
+    }
+
+    case "domain": {
+      const host = request.headers.get("host") || url.host;
+      const mapped = config.domains?.[host];
+      if (mapped) {
+        return { code: mapped, isDefault: false, strategy: "domain", source: host };
+      }
+      const cookie = readLocaleCookie(cookieHeader, cookieName, config.locales);
+      if (cookie) {
+        return { code: cookie, isDefault: false, strategy: "cookie", source: cookieHeader ?? undefined };
+      }
+      const accept = parseAcceptLanguage(acceptLanguage, config.locales);
+      if (accept) {
+        return { code: accept, isDefault: false, strategy: "header", source: acceptLanguage ?? undefined };
+      }
+      return finalFallback(config);
+    }
+
+    case "cookie": {
+      const cookie = readLocaleCookie(cookieHeader, cookieName, config.locales);
+      if (cookie) {
+        return { code: cookie, isDefault: false, strategy: "cookie", source: cookieHeader ?? undefined };
+      }
+      const accept = parseAcceptLanguage(acceptLanguage, config.locales);
+      if (accept) {
+        return { code: accept, isDefault: false, strategy: "header", source: acceptLanguage ?? undefined };
+      }
+      return finalFallback(config);
+    }
+
+    case "header": {
+      const accept = parseAcceptLanguage(acceptLanguage, config.locales);
+      if (accept) {
+        return { code: accept, isDefault: false, strategy: "header", source: acceptLanguage ?? undefined };
+      }
+      const cookie = readLocaleCookie(cookieHeader, cookieName, config.locales);
+      if (cookie) {
+        return { code: cookie, isDefault: false, strategy: "cookie", source: cookieHeader ?? undefined };
+      }
+      return finalFallback(config);
+    }
+  }
+
+  // Exhaustive check
+  return finalFallback(config);
+}
+
+function finalFallback(config: I18nDefinition): ResolvedLocale {
+  if (config.fallback && config.fallback !== config.defaultLocale) {
+    return {
+      code: config.fallback,
+      isDefault: config.fallback === config.defaultLocale,
+      strategy: "fallback",
+    };
+  }
+  return { code: config.defaultLocale, isDefault: true, strategy: "default" };
+}

package/src/i18n/message-registry.ts

@@ -0,0 +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
+  );
+}

package/src/i18n/types.ts

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

package/src/middleware/index.ts

@@ -29,6 +29,13 @@ export {
   rateLimitMiddleware,
 } from "./bridge";
 
+export {
+  schedulerCron,
+  setActiveSchedulerRegistration,
+  getActiveSchedulerRegistration,
+  type SchedulerCronMiddlewareOptions,
+} from "./scheduler-cron";
+
 export { cors, type CorsMiddlewareOptions } from "./cors";
 export { jwt, type JwtMiddlewareOptions } from "./jwt";
 export { csrf, type CsrfMiddlewareOptions } from "./csrf";

package/src/middleware/scheduler-cron.ts

@@ -0,0 +1,96 @@
+/**
+ * `scheduler-cron` — request-level middleware that exposes the running
+ * scheduler registration on `ctx` so handlers can inspect job status or
+ * trigger an ad-hoc tick for debugging.
+ *
+ * This is intentionally a thin bridge — the cron jobs themselves are
+ * defined with {@link import("../scheduler").defineCron} and started at
+ * `startServer()` boot time. The middleware does NOT start or stop the
+ * scheduler; its only job is to make the `CronRegistration` handle
+ * available to downstream request handlers (e.g., an observability
+ * dashboard API that wants to render `status()`).
+ *
+ * The middleware is opt-in — it's NOT part of the default chain. Add it
+ * to `mandu.config.ts` `middleware: [...]` only if you have a route that
+ * needs `ctx.scheduler`.
+ *
+ * @example
+ * ```ts
+ * // mandu.config.ts
+ * import { defineConfig } from "@mandujs/core";
+ * import { schedulerCron } from "@mandujs/core/middleware";
+ * import { jobs } from "./jobs";
+ *
+ * export default defineConfig({
+ *   scheduler: { jobs },
+ *   middleware: [schedulerCron()],
+ * });
+ * ```
+ */
+
+import { defineMiddleware } from "./define";
+import type { Middleware } from "./define";
+import type { CronRegistration } from "../scheduler";
+
+/**
+ * Global handle to the active {@link CronRegistration}, set by
+ * `startServer()` when it boots the scheduler. `scheduler-cron` middleware
+ * reads this slot on every request so the registration is always the one
+ * actually running.
+ *
+ * We store it on `globalThis` rather than module-scope so that multiple
+ * bundles (e.g., `@mandujs/core` loaded twice in a monorepo hot-reload)
+ * still see the same handle — matches the registry pattern in
+ * `runtime/server.ts`.
+ */
+const GLOBAL_KEY = "__MANDU_SCHEDULER_REGISTRATION__";
+
+interface SchedulerGlobal {
+  [GLOBAL_KEY]?: CronRegistration | null;
+}
+
+export function setActiveSchedulerRegistration(reg: CronRegistration | null): void {
+  (globalThis as unknown as SchedulerGlobal)[GLOBAL_KEY] = reg;
+}
+
+export function getActiveSchedulerRegistration(): CronRegistration | null {
+  return (globalThis as unknown as SchedulerGlobal)[GLOBAL_KEY] ?? null;
+}
+
+export interface SchedulerCronMiddlewareOptions {
+  /**
+   * Custom header to stamp on the response with the current scheduler job
+   * count. Useful for smoke-checking that the scheduler is running in a
+   * given environment. Default: no header is added.
+   */
+  statusHeader?: string;
+}
+
+/**
+ * Creates a middleware that exposes the scheduler registration via a response
+ * header and (optionally) stamps a status header. The registration itself is
+ * wired into `ctx` via the request-level composition chain — downstream
+ * code reads it with {@link getActiveSchedulerRegistration}.
+ */
+export function schedulerCron(options: SchedulerCronMiddlewareOptions = {}): Middleware {
+  return defineMiddleware({
+    name: "scheduler-cron",
+    async handler(_req, next) {
+      const response = await next();
+      const reg = getActiveSchedulerRegistration();
+      if (reg && options.statusHeader) {
+        const status = reg.status();
+        const jobCount = Object.keys(status).length;
+        // Clone headers to avoid mutating an immutable response body.
+        const headers = new Headers(response.headers);
+        headers.set(options.statusHeader, String(jobCount));
+        return new Response(response.body, {
+          status: response.status,
+          statusText: response.statusText,
+          headers,
+        });
+      }
+      return response;
+    },
+  });
+}