@buenojs/bueno 0.8.3 → 0.8.5

package/src/i18n/middleware.ts

@@ -0,0 +1,164 @@
+/**
+ * i18n Middleware — Locale Detection and Translation Binding
+ *
+ * Detects locale from cookie (priority 1) then Accept-Language header (priority 2),
+ * binds t() and locale to context, persists locale choice in a cookie.
+ */
+
+import type { Context } from "../context";
+import type { Middleware } from "../middleware";
+import { type I18n, createI18n } from "./engine";
+import type { I18nConfig, TranslationFunction } from "./types";
+
+// ============= Typed Context Helpers =============
+
+/**
+ * Get the current locale from context.
+ * Typed helper for accessing the locale set by i18nMiddleware.
+ *
+ * Returns the default locale ("en") if middleware has not run.
+ * Useful in route handlers:
+ *
+ * @example
+ * router.get('/locale', (ctx) => {
+ *   const locale = getLocale(ctx);  // 'fr', 'en', etc.
+ *   return ctx.json({ locale });
+ * });
+ *
+ * @param ctx Bueno Context instance
+ * @returns Current locale, or "en" if middleware hasn't run
+ */
+export function getLocale(ctx: Context): string {
+	return (ctx.get("locale") as string | undefined) ?? "en";
+}
+
+/**
+ * Get the bound translation function from context.
+ * Typed helper for accessing the t() set by i18nMiddleware.
+ *
+ * Returns an identity function (returns key as-is) if middleware has not run.
+ * Useful in route handlers:
+ *
+ * @example
+ * router.get('/greeting', (ctx) => {
+ *   const t = getT(ctx);
+ *   const message = t('greeting', { name: 'Alice' });
+ *   return ctx.text(message);
+ * });
+ *
+ * @param ctx Bueno Context instance
+ * @returns Translation function, or identity function if middleware hasn't run
+ */
+export function getT(ctx: Context): TranslationFunction {
+	return (ctx.get("t") as TranslationFunction | undefined) ?? ((key) => key);
+}
+
+// ============= Middleware Options =============
+
+/**
+ * Options for i18nMiddleware.
+ * Extends I18nConfig and adds an optional pre-constructed I18n instance.
+ */
+export interface I18nMiddlewareOptions extends I18nConfig {
+	/**
+	 * Pre-constructed I18n instance.
+	 * If not provided, one is created from the other options.
+	 *
+	 * Pass this when you want a single shared instance across multiple
+	 * middleware chains or route groups (prevents double-loading locale files).
+	 */
+	i18n?: I18n;
+}
+
+// ============= Middleware Factory =============
+
+/**
+ * Create i18n middleware.
+ *
+ * Locale detection priority:
+ * 1. Cookie (bueno_locale or custom cookieName)
+ * 2. Accept-Language header
+ * 3. Default locale (config.defaultLocale)
+ *
+ * Sets on context (available via getLocale/getT):
+ * - ctx.set('locale', detectedLocale)
+ * - ctx.set('t', translationFunction)
+ *
+ * Sets on response:
+ * - Set-Cookie header to persist locale choice
+ * - Vary: Accept-Language header (for correct CDN caching)
+ *
+ * @example
+ * ```typescript
+ * const router = new Router();
+ * router.use(i18nMiddleware({
+ *   defaultLocale: 'en',
+ *   supportedLocales: ['en', 'fr', 'de'],
+ *   basePath: 'resources/i18n'
+ * }));
+ *
+ * router.get('/hello', (ctx) => {
+ *   const locale = getLocale(ctx);
+ *   const t = getT(ctx);
+ *   return ctx.json({ message: t('greeting') });
+ * });
+ * ```
+ *
+ * @param options Configuration options
+ * @returns Koa-style middleware function
+ */
+export function i18nMiddleware(
+	options: I18nMiddlewareOptions = {},
+): Middleware {
+	const engine = options.i18n ?? createI18n(options);
+	const negotiator = engine.getNegotiator();
+	const cookieName = engine.config.cookieName;
+	const cookieMaxAge = engine.config.cookieMaxAge;
+
+	return async (
+		ctx: Context,
+		next: () => Promise<Response>,
+	): Promise<Response> => {
+		// --- Step 1: Detect locale ---
+		let locale: string;
+
+		// Priority 1: Cookie
+		const cookieLocale = ctx.getCookie(cookieName);
+		if (cookieLocale && negotiator.isSupported(cookieLocale)) {
+			locale = cookieLocale;
+		} else {
+			// Priority 2: Accept-Language header
+			const acceptLanguage = ctx.getHeader("accept-language") ?? "";
+			if (acceptLanguage) {
+				const match = negotiator.negotiate(acceptLanguage);
+				locale = match.locale;
+			} else {
+				locale = engine.config.defaultLocale;
+			}
+		}
+
+		// --- Step 2: Store on context ---
+		// Use 'as never' cast for now (same pattern as requestId middleware)
+		// Typed access via getLocale(ctx) and getT(ctx) helpers
+		ctx.set("locale" as never, locale);
+		ctx.set("t" as never, engine.createTranslator(locale));
+
+		// --- Step 3: Call next ---
+		const response = await next();
+
+		// --- Step 4: Set cookie on response ---
+		// Always refresh the cookie so it stays alive during user session
+		const cookieValue = `${cookieName}=${locale}; Max-Age=${cookieMaxAge}; Path=/; SameSite=Lax`;
+		response.headers.append("Set-Cookie", cookieValue);
+
+		// --- Step 5: Set Vary header ---
+		// Instruct caches to vary on Accept-Language so different locales are cached separately
+		const existing = response.headers.get("Vary");
+		response.headers.set(
+			"Vary",
+			existing ? `${existing}, Accept-Language` : "Accept-Language",
+		);
+
+		return response;
+	};
+}

package/src/i18n/negotiator.ts

@@ -0,0 +1,162 @@
+/**
+ * Locale Negotiation — Accept-Language Header Parsing
+ *
+ * Parses RFC 7231 Accept-Language headers and matches them against
+ * supported locales using exact and language-prefix matching.
+ *
+ * @see https://tools.ietf.org/html/rfc7231#section-5.3.5
+ */
+
+import type { LocaleMatch } from "./types";
+
+// ============= Types =============
+
+/**
+ * Parsed entry from an Accept-Language header.
+ */
+interface AcceptEntry {
+	locale: string; // e.g. "en-US"
+	quality: number; // 0.0–1.0, default 1.0
+}
+
+// ============= Parsing =============
+
+/**
+ * Parse RFC 7231 Accept-Language header value into quality-sorted entries.
+ *
+ * @example
+ * Input: "en-US,en;q=0.9,fr;q=0.8"
+ * Output: [
+ *   { locale: "en-US", quality: 1.0 },
+ *   { locale: "en", quality: 0.9 },
+ *   { locale: "fr", quality: 0.8 }
+ * ]
+ *
+ * @param header Raw Accept-Language header value
+ * @returns Array of entries sorted by quality (highest first)
+ */
+export function parseAcceptLanguage(header: string): AcceptEntry[] {
+	if (!header.trim()) return [];
+
+	return header
+		.split(",")
+		.map((part) => {
+			const [localeRaw, qRaw] = part.trim().split(";");
+			const locale = localeRaw?.trim() ?? "";
+			const quality = qRaw
+				? Number.parseFloat(qRaw.trim().replace("q=", ""))
+				: 1.0;
+			return { locale, quality: isNaN(quality) ? 1.0 : quality };
+		})
+		.filter((e) => e.locale.length > 0)
+		.sort((a, b) => b.quality - a.quality);
+}
+
+/**
+ * Normalise a locale tag:
+ * - Converts underscore to hyphen ("en_US" → "en-US")
+ * - Lowercases language subtag ("EN" → "en")
+ * - Uppercases region subtag ("us" → "US")
+ *
+ * @example
+ * normaliseLocale("en_US") → "en-US"
+ * normaliseLocale("EN-us") → "en-US"
+ * normaliseLocale("fr") → "fr"
+ *
+ * @param locale Raw locale string
+ * @returns Normalised locale string
+ */
+export function normaliseLocale(locale: string): string {
+	const parts = locale.replace("_", "-").split("-");
+	if (parts.length === 0) return locale;
+	const lang = parts[0]!.toLowerCase();
+	if (parts.length === 1) return lang;
+	const region = parts[1]!.toUpperCase();
+	return `${lang}-${region}`;
+}
+
+/**
+ * Extract the language subtag from a locale.
+ * @example languageSubtag("en-US") → "en"
+ * @param locale Locale identifier
+ * @returns Language subtag (first part before hyphen)
+ */
+function languageSubtag(locale: string): string {
+	return locale.split("-")[0]!.toLowerCase();
+}
+
+// ============= Negotiator =============
+
+/**
+ * Negotiates the best locale match given an Accept-Language header
+ * and a list of supported locales.
+ *
+ * Matching strategy (two-pass):
+ * 1. Exact match: find a supported locale that exactly matches (case-normalised) any entry
+ * 2. Language prefix match: find a supported locale whose language subtag matches any entry
+ * 3. Default: return the configured default locale
+ *
+ * This two-pass approach ensures correct behavior even when entries
+ * are out of quality order, e.g. "fr-CA,de;q=0.9" against ["de","fr"]
+ * should return "fr" (via prefix match), not "de".
+ */
+export class LocaleNegotiator {
+	private supported: string[];
+	private defaultLocale: string;
+
+	constructor(supportedLocales: string[], defaultLocale: string) {
+		this.supported = supportedLocales;
+		this.defaultLocale = defaultLocale;
+	}
+
+	/**
+	 * Find the best matching locale given a raw Accept-Language header string.
+	 *
+	 * @param acceptLanguageHeader Raw Accept-Language header value
+	 * @returns LocaleMatch with matched locale and strategy used
+	 */
+	negotiate(acceptLanguageHeader: string): LocaleMatch {
+		const entries = parseAcceptLanguage(acceptLanguageHeader);
+
+		// Pass 1: exact match (case-normalised)
+		for (const entry of entries) {
+			const norm = normaliseLocale(entry.locale);
+
+			const exact = this.supported.find((s) => normaliseLocale(s) === norm);
+			if (exact) {
+				return { locale: exact, strategy: "exact", source: entry.locale };
+			}
+		}
+
+		// Pass 2: language prefix match ("en-US" matches supported "en")
+		for (const entry of entries) {
+			const lang = languageSubtag(entry.locale);
+
+			const prefix = this.supported.find((s) => languageSubtag(s) === lang);
+			if (prefix) {
+				return { locale: prefix, strategy: "prefix", source: entry.locale };
+			}
+		}
+
+		// Default fallback
+		return {
+			locale: this.defaultLocale,
+			strategy: "default",
+			source: "",
+		};
+	}
+
+	/**
+	 * Validate whether a given locale string is in the supported list.
+	 * Used to validate cookie values before trusting them.
+	 *
+	 * Performs strict membership check — does not normalise or approximate.
+	 * If a cookie contains "fr-CA" but only "fr" is supported, this returns false.
+	 *
+	 * @param locale Locale to validate
+	 * @returns true if locale is in supportedLocales
+	 */
+	isSupported(locale: string): boolean {
+		return this.supported.includes(locale);
+	}
+}

package/src/i18n/types.ts

@@ -0,0 +1,158 @@
+/**
+ * i18n Types and Interfaces
+ *
+ * Core types for the internationalisation system:
+ * locale negotiation, translation lookup, plural forms, and configuration.
+ */
+
+// ============= CLDR Plural Keys =============
+
+/**
+ * CLDR-standard plural form categories.
+ * Used to select the appropriate plural variant of a translation.
+ *
+ * @see https://cldr.unicode.org/index/cldr-spec/plural-rules
+ */
+export type PluralKey = "zero" | "one" | "two" | "few" | "many" | "other";
+
+// ============= Translation Types =============
+
+/**
+ * Raw translation file shape — can be flat or nested JSON.
+ * @example
+ * { "nav.home": "Home" } or { "nav": { "home": "Home" } }
+ */
+export type TranslationMap = Record<string, unknown>;
+
+/**
+ * Flat map of dot-notation keys → string values.
+ * The loader always normalises nested keys to this format before caching.
+ * @example
+ * Map { "nav.home" → "Home", "nav.about" → "About" }
+ */
+export type FlatTranslations = Map<string, string>;
+
+/**
+ * Parameters passed to the translation function.
+ * `count` is special — it drives plural form selection.
+ * Other keys are used for variable interpolation ({{ key }}).
+ */
+export interface TranslationParams {
+	count?: number;
+	[key: string]: unknown;
+}
+
+/**
+ * The t() function signature stored on context and returned by the engine.
+ * @example
+ * t('greeting', { name: 'Alice' }) → "Hello, Alice!"
+ */
+export type TranslationFunction = (
+	key: string,
+	params?: TranslationParams,
+) => string;
+
+// ============= Locale Negotiation =============
+
+/**
+ * Result of a locale negotiation attempt against supported locales.
+ * Used to determine which locale to load based on client preferences.
+ */
+export interface LocaleMatch {
+	/** The matched locale from supportedLocales (e.g. "fr") */
+	locale: string;
+	/** How the match was found: exact string match, language prefix match, or default */
+	strategy: "exact" | "prefix" | "default";
+	/** The original value that was negotiated (e.g. "fr-CA" from Accept-Language) */
+	source: string;
+}
+
+// ============= I18n Context (what is stored on ctx) =============
+
+/**
+ * What the middleware stores on the Bueno Context instance.
+ * Accessed via ctx.get('locale') and ctx.get('t').
+ * Typed helpers getLocale(ctx) and getT(ctx) are recommended.
+ */
+export interface I18nContext {
+	locale: string;
+	t: TranslationFunction;
+}
+
+// ============= I18n Configuration =============
+
+/**
+ * User-facing i18n configuration.
+ * All fields are optional; defaults are applied by the engine.
+ * Environment variable pattern: BUENO_I18N_*
+ */
+export interface I18nConfig {
+	/** Enable/disable the i18n system (default: false) */
+	enabled?: boolean;
+	/** Default locale — used as fallback when requested locale has missing keys (default: "en") */
+	defaultLocale?: string;
+	/** List of all supported locale identifiers (default: ["en"]) */
+	supportedLocales?: string[];
+	/** Base directory for locale JSON files (default: "resources/i18n") */
+	basePath?: string;
+	/**
+	 * When a key is missing in the requested locale,
+	 * fall back to the defaultLocale before returning the key string (default: true)
+	 */
+	fallbackToDefault?: boolean;
+	/** Cookie name used to persist locale choice (default: "bueno_locale") */
+	cookieName?: string;
+	/** Cookie max-age in seconds (default: 31536000 = 1 year) */
+	cookieMaxAge?: number;
+	/** Enable file watching for hot reload in development (default: false) */
+	watch?: boolean;
+}
+
+// ============= Resolved I18n Config (internal) =============
+
+/**
+ * Fully-resolved i18n configuration with all defaults applied.
+ * All fields are required (non-optional) — used internally by the engine.
+ */
+export interface ResolvedI18nConfig {
+	defaultLocale: string;
+	supportedLocales: string[];
+	basePath: string;
+	fallbackToDefault: boolean;
+	cookieName: string;
+	cookieMaxAge: number;
+}
+
+// ============= Loader Types =============
+
+/**
+ * A loaded and cached locale bundle.
+ * Contains flattened translations and metadata.
+ */
+export interface LocaleBundle {
+	/** Locale identifier e.g. "en", "fr-CA" */
+	locale: string;
+	/** Flat dot-notation key → string value map */
+	translations: FlatTranslations;
+	/** When this bundle was loaded (ms epoch) */
+	loadedAt: number;
+}
+
+// ============= Metrics =============
+
+/**
+ * Metrics collected by the translation engine.
+ * Useful for debugging and performance monitoring.
+ */
+export interface I18nMetrics {
+	/** Total number of t() calls */
+	totalLookups: number;
+	/** Lookups that found a key in the requested locale */
+	hits: number;
+	/** Lookups that fell back to the default locale */
+	fallbacks: number;
+	/** Lookups that returned the key string (complete miss) */
+	misses: number;
+	/** Locales currently loaded in memory */
+	loadedLocales: string[];
+}