@buenojs/bueno 0.8.10 → 0.8.11

package/dist/i18n/loader.js

@@ -0,0 +1,192 @@
+/**
+ * Translation Loader — JSON File Loading and Caching
+ *
+ * Loads locale JSON files from disk, flattens nested keys to dot-notation,
+ * caches in memory, and supports hot-reload via file watching.
+ */
+import { existsSync, readFileSync, watch } from "fs";
+import { join, resolve } from "path";
+// ============= Flattening =============
+/**
+ * Recursively flatten a nested object into dot-notation keys.
+ *
+ * @example
+ * flattenTranslations({ nav: { home: "Home", about: "About" } })
+ * → Map { "nav.home" → "Home", "nav.about" → "About" }
+ *
+ * Already-flat keys pass through unchanged.
+ * Non-string leaf values are converted via String().
+ * Arrays are not recursed — they are stringified as-is.
+ *
+ * @param obj Object to flatten (or nested structure)
+ * @param prefix Current dot-notation prefix (used recursively)
+ * @param result Accumulator map (used recursively)
+ * @returns Flattened Map with all keys in dot-notation form
+ */
+function flattenTranslations(obj, prefix = "", result = new Map()) {
+    for (const [key, value] of Object.entries(obj)) {
+        const dotKey = prefix ? `${prefix}.${key}` : key;
+        if (value !== null && typeof value === "object" && !Array.isArray(value)) {
+            flattenTranslations(value, dotKey, result);
+        }
+        else {
+            result.set(dotKey, String(value ?? ""));
+        }
+    }
+    return result;
+}
+// ============= Loader =============
+/**
+ * Loads and caches locale translation bundles from JSON files.
+ * Supports file watching for hot-reload in development.
+ */
+export class TranslationLoader {
+    cache = new Map();
+    watchers = new Map();
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    /**
+     * Load a locale bundle. Returns from cache if already loaded.
+     *
+     * For the default locale:
+     *   - Throws if the file is not found (cannot proceed without defaults)
+     *
+     * For non-default locales:
+     *   - Returns an empty bundle if the file is not found
+     *   - Fallback in the engine will handle the miss
+     *
+     * @param locale Locale identifier to load
+     * @returns LocaleBundle with flattened translations
+     * @throws Error if default locale file is not found
+     */
+    load(locale) {
+        const cached = this.cache.get(locale);
+        if (cached)
+            return cached;
+        return this._loadFromDisk(locale);
+    }
+    /**
+     * Pre-load all supported locales eagerly.
+     * Call this once at application startup for best performance.
+     *
+     * Non-default locales that are missing are silently skipped
+     * (returning empty bundles).
+     */
+    preload() {
+        for (const locale of this.config.supportedLocales) {
+            try {
+                this._loadFromDisk(locale);
+            }
+            catch {
+                // Non-default locales may legitimately have no file yet
+                if (locale !== this.config.defaultLocale) {
+                    this.cache.set(locale, {
+                        locale,
+                        translations: new Map(),
+                        loadedAt: Date.now(),
+                    });
+                }
+            }
+        }
+    }
+    /**
+     * Invalidate a locale's cache entry.
+     * Forces a reload from disk on the next access.
+     *
+     * @param locale Locale to invalidate
+     */
+    invalidate(locale) {
+        this.cache.delete(locale);
+    }
+    /**
+     * Return all currently loaded locale names.
+     *
+     * @returns Array of loaded locale identifiers
+     */
+    loadedLocales() {
+        return Array.from(this.cache.keys());
+    }
+    /**
+     * Enable file watching for a locale (hot reload in dev mode).
+     * Invalidates cache and reloads on file change.
+     *
+     * @param locale Locale file to watch
+     */
+    watch(locale) {
+        const filePath = this._resolvePath(locale);
+        if (!existsSync(filePath))
+            return;
+        if (this.watchers.has(locale))
+            return;
+        const watcher = watch(filePath, () => {
+            this.invalidate(locale);
+            try {
+                this._loadFromDisk(locale);
+            }
+            catch {
+                // Ignore parse errors during hot reload — log in production
+            }
+        });
+        this.watchers.set(locale, watcher);
+    }
+    /**
+     * Stop all file watchers.
+     * Call this when the application shuts down.
+     */
+    stopWatching() {
+        for (const watcher of this.watchers.values()) {
+            watcher.close();
+        }
+        this.watchers.clear();
+    }
+    // ============= Private Helpers =============
+    /**
+     * Resolve the full file path for a locale.
+     * @param locale Locale identifier
+     * @returns Full file path to the locale JSON file
+     */
+    _resolvePath(locale) {
+        return resolve(join(this.config.basePath, `${locale}.json`));
+    }
+    /**
+     * Load a locale file from disk and cache it.
+     * @param locale Locale to load
+     * @returns LocaleBundle with flattened translations
+     * @throws Error if default locale file is not found or JSON is invalid
+     */
+    _loadFromDisk(locale) {
+        const filePath = this._resolvePath(locale);
+        if (!existsSync(filePath)) {
+            if (locale === this.config.defaultLocale) {
+                throw new Error(`[i18n] Default locale file not found: ${filePath}. ` +
+                    `Create ${locale}.json in ${this.config.basePath}`);
+            }
+            // For non-default locales, silently return an empty bundle
+            const empty = {
+                locale,
+                translations: new Map(),
+                loadedAt: Date.now(),
+            };
+            this.cache.set(locale, empty);
+            return empty;
+        }
+        const raw = readFileSync(filePath, "utf-8");
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch (err) {
+            throw new Error(`[i18n] Failed to parse locale file ${filePath}: ${String(err)}`);
+        }
+        const bundle = {
+            locale,
+            translations: flattenTranslations(parsed),
+            loadedAt: Date.now(),
+        };
+        this.cache.set(locale, bundle);
+        return bundle;
+    }
+}
+//# sourceMappingURL=loader.js.map

package/dist/i18n/loader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"loader.js","sourceRoot":"","sources":["../../src/i18n/loader.ts"],"names":[],"mappings":"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"}

package/dist/i18n/middleware.d.ts

@@ -0,0 +1,96 @@
+/**
+ * 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 } from "./engine";
+import type { I18nConfig, TranslationFunction } from "./types";
+/**
+ * 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 declare function getLocale(ctx: Context): string;
+/**
+ * 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 declare function getT(ctx: Context): TranslationFunction;
+/**
+ * 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;
+}
+/**
+ * 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 declare function i18nMiddleware(options?: I18nMiddlewareOptions): Middleware;
+//# sourceMappingURL=middleware.d.ts.map

package/dist/i18n/middleware.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"middleware.d.ts","sourceRoot":"","sources":["../../src/i18n/middleware.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAAE,KAAK,IAAI,EAAc,MAAM,UAAU,CAAC;AACjD,OAAO,KAAK,EAAE,UAAU,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AAI/D;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAE9C;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,IAAI,CAAC,GAAG,EAAE,OAAO,GAAG,mBAAmB,CAEtD;AAID;;;GAGG;AACH,MAAM,WAAW,qBAAsB,SAAQ,UAAU;IACxD;;;;;;OAMG;IACH,IAAI,CAAC,EAAE,IAAI,CAAC;CACZ;AAID;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAgB,cAAc,CAC7B,OAAO,GAAE,qBAA0B,GACjC,UAAU,CAoDZ"}

package/dist/i18n/middleware.js

@@ -0,0 +1,126 @@
+/**
+ * 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 { createI18n } from "./engine";
+// ============= 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) {
+    return ctx.get("locale") ?? "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) {
+    return ctx.get("t") ?? ((key) => key);
+}
+// ============= 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 = {}) {
+    const engine = options.i18n ?? createI18n(options);
+    const negotiator = engine.getNegotiator();
+    const cookieName = engine.config.cookieName;
+    const cookieMaxAge = engine.config.cookieMaxAge;
+    return async (ctx, next) => {
+        // --- Step 1: Detect locale ---
+        let locale;
+        // 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", locale);
+        ctx.set("t", 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;
+    };
+}
+//# sourceMappingURL=middleware.js.map

package/dist/i18n/middleware.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"middleware.js","sourceRoot":"","sources":["../../src/i18n/middleware.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,EAAa,UAAU,EAAE,MAAM,UAAU,CAAC;AAGjD,oDAAoD;AAEpD;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,SAAS,CAAC,GAAY;IACrC,OAAQ,GAAG,CAAC,GAAG,CAAC,QAAQ,CAAwB,IAAI,IAAI,CAAC;AAC1D,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,IAAI,CAAC,GAAY;IAChC,OAAQ,GAAG,CAAC,GAAG,CAAC,GAAG,CAAqC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC;AAC5E,CAAC;AAmBD,iDAAiD;AAEjD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,MAAM,UAAU,cAAc,CAC7B,UAAiC,EAAE;IAEnC,MAAM,MAAM,GAAG,OAAO,CAAC,IAAI,IAAI,UAAU,CAAC,OAAO,CAAC,CAAC;IACnD,MAAM,UAAU,GAAG,MAAM,CAAC,aAAa,EAAE,CAAC;IAC1C,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,CAAC,UAAU,CAAC;IAC5C,MAAM,YAAY,GAAG,MAAM,CAAC,MAAM,CAAC,YAAY,CAAC;IAEhD,OAAO,KAAK,EACX,GAAY,EACZ,IAA6B,EACT,EAAE;QACtB,gCAAgC;QAChC,IAAI,MAAc,CAAC;QAEnB,qBAAqB;QACrB,MAAM,YAAY,GAAG,GAAG,CAAC,SAAS,CAAC,UAAU,CAAC,CAAC;QAC/C,IAAI,YAAY,IAAI,UAAU,CAAC,WAAW,CAAC,YAAY,CAAC,EAAE,CAAC;YAC1D,MAAM,GAAG,YAAY,CAAC;QACvB,CAAC;aAAM,CAAC;YACP,qCAAqC;YACrC,MAAM,cAAc,GAAG,GAAG,CAAC,SAAS,CAAC,iBAAiB,CAAC,IAAI,EAAE,CAAC;YAC9D,IAAI,cAAc,EAAE,CAAC;gBACpB,MAAM,KAAK,GAAG,UAAU,CAAC,SAAS,CAAC,cAAc,CAAC,CAAC;gBACnD,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC;YACvB,CAAC;iBAAM,CAAC;gBACP,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,aAAa,CAAC;YACtC,CAAC;QACF,CAAC;QAED,mCAAmC;QACnC,qEAAqE;QACrE,wDAAwD;QACxD,GAAG,CAAC,GAAG,CAAC,QAAiB,EAAE,MAAM,CAAC,CAAC;QACnC,GAAG,CAAC,GAAG,CAAC,GAAY,EAAE,MAAM,CAAC,gBAAgB,CAAC,MAAM,CAAC,CAAC,CAAC;QAEvD,4BAA4B;QAC5B,MAAM,QAAQ,GAAG,MAAM,IAAI,EAAE,CAAC;QAE9B,yCAAyC;QACzC,kEAAkE;QAClE,MAAM,WAAW,GAAG,GAAG,UAAU,IAAI,MAAM,aAAa,YAAY,wBAAwB,CAAC;QAC7F,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,YAAY,EAAE,WAAW,CAAC,CAAC;QAEnD,kCAAkC;QAClC,wFAAwF;QACxF,MAAM,QAAQ,GAAG,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QAC9C,QAAQ,CAAC,OAAO,CAAC,GAAG,CACnB,MAAM,EACN,QAAQ,CAAC,CAAC,CAAC,GAAG,QAAQ,mBAAmB,CAAC,CAAC,CAAC,iBAAiB,CAC7D,CAAC;QAEF,OAAO,QAAQ,CAAC;IACjB,CAAC,CAAC;AACH,CAAC"}

package/dist/i18n/negotiator.d.ts

@@ -0,0 +1,84 @@
+/**
+ * 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";
+/**
+ * Parsed entry from an Accept-Language header.
+ */
+interface AcceptEntry {
+    locale: string;
+    quality: number;
+}
+/**
+ * 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 declare function parseAcceptLanguage(header: string): AcceptEntry[];
+/**
+ * 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 declare function normaliseLocale(locale: string): string;
+/**
+ * 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 declare class LocaleNegotiator {
+    private supported;
+    private defaultLocale;
+    constructor(supportedLocales: string[], defaultLocale: string);
+    /**
+     * 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;
+    /**
+     * 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;
+}
+export {};
+//# sourceMappingURL=negotiator.d.ts.map

package/dist/i18n/negotiator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"negotiator.d.ts","sourceRoot":"","sources":["../../src/i18n/negotiator.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAI3C;;GAEG;AACH,UAAU,WAAW;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;CAChB;AAID;;;;;;;;;;;;;GAaG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,WAAW,EAAE,CAejE;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAOtD;AAcD;;;;;;;;;;;;GAYG;AACH,qBAAa,gBAAgB;IAC5B,OAAO,CAAC,SAAS,CAAW;IAC5B,OAAO,CAAC,aAAa,CAAS;gBAElB,gBAAgB,EAAE,MAAM,EAAE,EAAE,aAAa,EAAE,MAAM;IAK7D;;;;;OAKG;IACH,SAAS,CAAC,oBAAoB,EAAE,MAAM,GAAG,WAAW;IA+BpD;;;;;;;;;OASG;IACH,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO;CAGpC"}

package/dist/i18n/negotiator.js

@@ -0,0 +1,139 @@
+/**
+ * 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
+ */
+// ============= 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) {
+    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) {
+    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) {
+    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 {
+    supported;
+    defaultLocale;
+    constructor(supportedLocales, defaultLocale) {
+        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) {
+        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) {
+        return this.supported.includes(locale);
+    }
+}
+//# sourceMappingURL=negotiator.js.map

package/dist/i18n/negotiator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"negotiator.js","sourceRoot":"","sources":["../../src/i18n/negotiator.ts"],"names":[],"mappings":"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"}