intor 2.3.14 → 2.3.15

package/dist/core/src/config/resolvers/resolve-fallback-locales.js

@@ -12,7 +12,7 @@ const resolveFallbackLocales = (config, id, supportedSet) => {
     if (!fallbackLocales || typeof fallbackLocales !== "object") {
         return {};
     }
-    const logger = getLogger({ id }).child({
+    const logger = getLogger({ ...config.logger, id }).child({
         scope: "resolve-fallback-locales",
     });
     const resolvedMap = {};

package/dist/core/src/core/messages/utils/is-valid-messages.js

@@ -3,15 +3,10 @@ function isPlainObject(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 /**
- * Check if a value is a valid **Messages** object.
+ * Check if a value is a valid MessageObject.
  *
- * - Uses an iterative approach to avoid stack overflow with deeply nested objects.
- *
- * @example
- * ```ts
- * isValidMessages({ en: { hello: "Hello" } }) // true
- * isValidMessages({ en: { count: 5 } }) // false
- * ```
+ * - Supports all MessageValue variants (primitive, array, object).
+ * - Uses an iterative approach to avoid stack overflow.
  */
 function isValidMessages(value) {
     if (!isPlainObject(value))
@@ -19,16 +14,29 @@ function isValidMessages(value) {
     const stack = [value];
     while (stack.length > 0) {
         const current = stack.pop();
-        for (const v of Object.values(current)) {
-            if (typeof v === "string")
-                continue;
-            if (isPlainObject(v)) {
-                stack.push(v);
+        // primitives are always valid
+        if (current === null ||
+            typeof current === "string" ||
+            typeof current === "number" ||
+            typeof current === "boolean") {
+            continue;
+        }
+        // array → validate each item
+        if (Array.isArray(current)) {
+            for (const item of current) {
+                stack.push(item);
             }
-            else {
-                return false;
+            continue;
+        }
+        // object → validate each value
+        if (isPlainObject(current)) {
+            for (const v of Object.values(current)) {
+                stack.push(v);
             }
+            continue;
         }
+        // everything else is invalid
+        return false;
     }
     return true;
 }

package/dist/core/src/server/helpers/get-translator.js

@@ -2,11 +2,11 @@ import { createIntorRuntime } from '../runtime/create-intor-runtime.js';
 
 // Implementation
 async function getTranslator(config, params) {
-    const { readOptions, allowCacheWrite, preKey, handlers, plugins } = params;
+    const { readers, allowCacheWrite, preKey, handlers, plugins } = params;
     const locale = params.locale;
     // Create runtime (request-scoped, no cache write)
     const runtime = createIntorRuntime(config, {
-        readOptions,
+        readers,
         allowCacheWrite,
     });
     // Ensure messages & create translator snapshot
@@ -21,6 +21,7 @@ async function getTranslator(config, params) {
         locale,
         hasKey: translator.hasKey,
         t: translator.t,
+        tRaw: translator.tRaw,
     };
 }
 

package/dist/core/src/server/helpers/local-messages-from-url.js

@@ -43,7 +43,7 @@ async function loadMessagesFromUrl(url, options) {
         namespaces,
         fallbackLocales,
         concurrency: options?.concurrency,
-        readOptions: options?.readOptions,
+        readers: options?.readers,
         pool: options?.pool,
         allowCacheWrite: options?.allowCacheWrite,
         loggerOptions: options?.loggerOptions || { id: "default" },

package/dist/core/src/server/messages/load-local-messages/load-local-messages.js

@@ -21,7 +21,7 @@ import { readLocaleMessages } from './read-locale-messages/read-locale-messages.
  *
  * File traversal, parsing, and validation are delegated to lower-level utilities.
  */
-const loadLocalMessages = async ({ id, locale, fallbackLocales, namespaces, rootDir = "messages", concurrency = 10, readOptions, pool = getGlobalMessagesPool(), allowCacheWrite = false, loggerOptions, }) => {
+const loadLocalMessages = async ({ id, locale, fallbackLocales, namespaces, rootDir = "messages", concurrency = 10, readers, pool = getGlobalMessagesPool(), allowCacheWrite = false, loggerOptions, }) => {
     const baseLogger = getLogger(loggerOptions);
     const logger = baseLogger.child({ scope: "load-local-messages" });
     const start = performance.now();
@@ -65,7 +65,7 @@ const loadLocalMessages = async ({ id, locale, fallbackLocales, namespaces, root
                 namespaces,
                 rootDir,
                 limit,
-                readOptions,
+                readers,
                 loggerOptions,
             });
             // Stop at the first locale that yields non-empty messages

package/dist/core/src/server/messages/load-local-messages/read-locale-messages/collect-file-entries/collect-file-entries.js

@@ -20,9 +20,10 @@ import { getLogger } from '../../../../../core/logger/get-logger.js';
  * }, ... ];
  * ```
  */
-async function collectFileEntries({ readdir = fs.readdir, namespaces, rootDir, limit, exts = [".json"], loggerOptions, }) {
+async function collectFileEntries({ readdir = fs.readdir, namespaces, rootDir, limit, exts = ["json"], loggerOptions, }) {
     const baseLogger = getLogger(loggerOptions);
     const logger = baseLogger.child({ scope: "collect-file-entries" });
+    const supportedExts = new Set(["json", ...exts]);
     const fileEntries = [];
     // Recursive directory walk
     const walk = async (currentDir) => {
@@ -50,14 +51,14 @@ async function collectFileEntries({ readdir = fs.readdir, namespaces, rootDir, l
                 return;
             }
             // Skip unsupported file extensions
-            if (!exts.some((ext) => entry.name.endsWith(ext)))
+            const ext = path.extname(entry.name).slice(1); // "json", "yaml"
+            if (!ext || !supportedExts.has(ext))
                 return;
             // ---------------------------------------------------------------------
             // Resolve file entry
             // ---------------------------------------------------------------------
             const relativePath = path.relative(rootDir, fullPath);
-            const ext = path.extname(relativePath);
-            const withoutExt = relativePath.slice(0, -ext.length);
+            const withoutExt = relativePath.slice(0, relativePath.length - (ext.length + 1));
             const segments = withoutExt.split(path.sep).filter(Boolean);
             const namespace = segments.at(0);
             if (!namespace)
@@ -72,7 +73,7 @@ async function collectFileEntries({ readdir = fs.readdir, namespaces, rootDir, l
                 fullPath,
                 relativePath,
                 segments,
-                basename: path.basename(entry.name, ext),
+                basename: path.basename(entry.name, `.${ext}`),
             });
         }));
         await Promise.all(tasks);

package/dist/core/src/server/messages/load-local-messages/read-locale-messages/parse-file-entries/parse-file-entries.js

@@ -35,7 +35,7 @@ import { nestObjectFromPath } from './utils/nest-object-from-path.js';
  * }
  * ```
  */
-async function parseFileEntries({ fileEntries, limit, messagesReader, loggerOptions, }) {
+async function parseFileEntries({ fileEntries, limit, readers, loggerOptions, }) {
     const baseLogger = getLogger(loggerOptions);
     const logger = baseLogger.child({ scope: "parse-file-entries" });
     // Read and parse all file entries
@@ -45,10 +45,19 @@ async function parseFileEntries({ fileEntries, limit, messagesReader, loggerOpti
             // -------------------------------------------------------------------
             // Read and validate file content
             // -------------------------------------------------------------------
-            const ext = path.extname(fullPath);
-            const raw = ext !== ".json" && messagesReader
-                ? await messagesReader(fullPath)
-                : await jsonReader(fullPath);
+            const ext = path.extname(fullPath).slice(1); // remove dot
+            let raw;
+            if (ext === "json") {
+                raw = await jsonReader(fullPath);
+            }
+            else {
+                const reader = readers?.[ext];
+                if (!reader) {
+                    throw new Error(`No message reader registered for .${ext} files. ` +
+                        `Please register a reader for the "${ext}" extension.`);
+                }
+                raw = await reader(fullPath);
+            }
             // Validate messages structure
             if (!isValidMessages(raw)) {
                 throw new Error("Parsed content does not match expected Messages structure");

package/dist/core/src/server/messages/load-local-messages/read-locale-messages/read-locale-messages.js

@@ -12,7 +12,7 @@ import { parseFileEntries } from './parse-file-entries/parse-file-entries.js';
  *
  * It does not perform validation or transformation itself.
  */
-const readLocaleMessages = async ({ locale, namespaces, rootDir = "messages", limit, readOptions: { exts, messagesReader } = {}, loggerOptions, }) => {
+const readLocaleMessages = async ({ locale, namespaces, rootDir = "messages", limit, readers, loggerOptions, }) => {
     // ---------------------------------------------------------------------------
     // Collect message file entries for the locale
     // ---------------------------------------------------------------------------
@@ -20,7 +20,7 @@ const readLocaleMessages = async ({ locale, namespaces, rootDir = "messages", li
         namespaces,
         rootDir: path.resolve(rootDir, locale),
         limit,
-        exts,
+        exts: Object.keys(readers || {}),
         loggerOptions,
     });
     // ---------------------------------------------------------------------------
@@ -29,7 +29,7 @@ const readLocaleMessages = async ({ locale, namespaces, rootDir = "messages", li
     const messages = await parseFileEntries({
         fileEntries,
         limit,
-        messagesReader,
+        readers,
         loggerOptions,
     });
     // ---------------------------------------------------------------------------

package/dist/core/src/server/messages/load-messages.js

@@ -17,7 +17,7 @@ import { loadLocalMessages } from './load-local-messages/load-local-messages.js'
  * Message traversal, parsing, fallback resolution, and caching logic
  * are delegated to the selected loader.
  */
-const loadMessages = async ({ config, locale, readOptions, allowCacheWrite = false, }) => {
+const loadMessages = async ({ config, locale, readers, allowCacheWrite = false, }) => {
     const baseLogger = getLogger(config.logger);
     const logger = baseLogger.child({ scope: "load-messages" });
     // ---------------------------------------------------------------------------
@@ -35,8 +35,8 @@ const loadMessages = async ({ config, locale, readOptions, allowCacheWrite = fal
         loaderType: type,
         rootDir,
         locale,
-        fallbackLocales,
-        namespaces: namespaces && namespaces.length > 0 ? [...namespaces] : ["*"],
+        fallbackLocales: fallbackLocales.join(", "),
+        namespaces: namespaces && namespaces.length > 0 ? [...namespaces] : "*",
     });
     // ---------------------------------------------------------------------------
     // Dispatch to loader implementation
@@ -50,7 +50,7 @@ const loadMessages = async ({ config, locale, readOptions, allowCacheWrite = fal
             namespaces,
             rootDir,
             concurrency: loader.concurrency,
-            readOptions,
+            readers,
             allowCacheWrite,
             loggerOptions: config.logger,
         });

package/dist/core/src/server/runtime/create-intor-runtime.js

@@ -1,4 +1,5 @@
 import { IntorError, IntorErrorCode } from '../../core/error/intor-error.js';
+import { resolveLoaderOptions } from '../../core/utils/resolve-loader-options.js';
 import 'logry';
 import { loadMessages } from '../messages/load-messages.js';
 import { createTranslator } from '../translator/create-translator.js';
@@ -13,20 +14,24 @@ import { createTranslator } from '../translator/create-translator.js';
  * before a translator snapshot can be created.
  */
 function createIntorRuntime(config, options) {
+    const loader = resolveLoaderOptions(config, "server");
     // Locale that has completed the ensureMessages() phase
     let ensuredLocale;
     // Messages prepared during ensureMessages(); may be empty
     let ensuredMessages;
     return {
         async ensureMessages(locale) {
-            const messages = await loadMessages({
-                config,
-                locale,
-                readOptions: options?.readOptions,
-                allowCacheWrite: options?.allowCacheWrite ?? false,
-            });
+            let messages;
+            if (loader) {
+                messages = await loadMessages({
+                    config,
+                    locale,
+                    readers: options?.readers,
+                    allowCacheWrite: options?.allowCacheWrite || false,
+                });
+            }
             ensuredLocale = locale;
-            ensuredMessages = messages;
+            ensuredMessages = messages || {};
         },
         translator(locale, options) {
             // Guard: translator requires ensureMessages() to be completed for this locale

package/dist/core/src/server/translator/create-translator.js

@@ -34,6 +34,7 @@ function createTranslator(params) {
         locale,
         hasKey: scoped ? scoped.hasKey : translator.hasKey,
         t: scoped ? scoped.t : translator.t,
+        tRaw: scoped ? scoped.tRaw : translator.tRaw,
     };
 }
 

package/dist/express/src/adapters/express/helpers/get-translator.js

@@ -8,14 +8,14 @@ import { getTranslator as getTranslator$1 } from '../../../server/helpers/get-tr
 
 // Implementation
 async function getTranslator(config, req, params) {
-    const { preKey, handlers, plugins, readOptions } = params || {};
+    const { preKey, handlers, plugins, readers, allowCacheWrite } = params || {};
     return getTranslator$1(config, {
         locale: req.intor?.locale || config.defaultLocale,
         preKey,
         handlers,
         plugins,
-        readOptions,
-        allowCacheWrite: false,
+        readers,
+        allowCacheWrite,
     });
 }
 

package/dist/express/src/adapters/express/middleware/create-intor.js

@@ -24,7 +24,7 @@ function createIntor(config, options) {
     return async function intorMiddleware(req, _res, next) {
         // locale from accept-language header
         const acceptLanguage = req.headers["accept-language"];
-        const localeFromAcceptLanguage = getLocaleFromAcceptLanguage(config, acceptLanguage);
+        const localeFromAcceptLanguage = getLocaleFromAcceptLanguage(acceptLanguage, config.supportedLocales);
         // ----------------------------------------------------------
         // Resolve inbound routing decision (pure computation)
         // ----------------------------------------------------------
@@ -43,19 +43,20 @@ function createIntor(config, options) {
         // --------------------------------------------------
         // Bind inbound routing context
         // --------------------------------------------------
-        const { t, hasKey } = (await getTranslator(config, {
+        const { hasKey, t, tRaw } = (await getTranslator(config, {
             locale,
             handlers: options?.handlers,
             plugins: options?.plugins,
-            readOptions: options?.readOptions,
+            readers: options?.readers,
             allowCacheWrite: true,
         }));
         req.intor = { locale, localeSource };
         // DX shortcuts (optional)
         req.locale = locale;
         req.localeSource = localeSource;
-        req.t = t;
         req.hasKey = hasKey;
+        req.t = t;
+        req.tRaw = tRaw;
         return next();
     };
 }

package/dist/express/src/core/messages/utils/is-valid-messages.js

@@ -3,15 +3,10 @@ function isPlainObject(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 /**
- * Check if a value is a valid **Messages** object.
+ * Check if a value is a valid MessageObject.
  *
- * - Uses an iterative approach to avoid stack overflow with deeply nested objects.
- *
- * @example
- * ```ts
- * isValidMessages({ en: { hello: "Hello" } }) // true
- * isValidMessages({ en: { count: 5 } }) // false
- * ```
+ * - Supports all MessageValue variants (primitive, array, object).
+ * - Uses an iterative approach to avoid stack overflow.
  */
 function isValidMessages(value) {
     if (!isPlainObject(value))
@@ -19,16 +14,29 @@ function isValidMessages(value) {
     const stack = [value];
     while (stack.length > 0) {
         const current = stack.pop();
-        for (const v of Object.values(current)) {
-            if (typeof v === "string")
-                continue;
-            if (isPlainObject(v)) {
-                stack.push(v);
+        // primitives are always valid
+        if (current === null ||
+            typeof current === "string" ||
+            typeof current === "number" ||
+            typeof current === "boolean") {
+            continue;
+        }
+        // array → validate each item
+        if (Array.isArray(current)) {
+            for (const item of current) {
+                stack.push(item);
             }
-            else {
-                return false;
+            continue;
+        }
+        // object → validate each value
+        if (isPlainObject(current)) {
+            for (const v of Object.values(current)) {
+                stack.push(v);
             }
+            continue;
         }
+        // everything else is invalid
+        return false;
     }
     return true;
 }

package/dist/express/src/routing/inbound/resolve-inbound.js

@@ -1,5 +1,3 @@
-import '../../core/error/intor-error.js';
-import 'logry';
 import { getLocaleFromPathname } from '../locale/get-locale-from-pathname.js';
 import { getLocaleFromHost } from '../locale/get-locale-from-host.js';
 import { getLocaleFromQuery } from '../locale/get-locale-from-query.js';
@@ -20,11 +18,13 @@ async function resolveInbound(config, rawPathname, hasRedirected, localeInputs)
     // ------------------------------------------------------
     // Resolve locale from inbound inputs
     // ------------------------------------------------------
-    const pathLocale = getLocaleFromPathname(config, rawPathname);
+    const pathLocale = getLocaleFromPathname(rawPathname, config);
     const { locale, localeSource } = resolveLocale(config, {
         path: { locale: pathLocale },
-        host: { locale: getLocaleFromHost(config, host) },
-        query: { locale: getLocaleFromQuery(config, query) },
+        host: { locale: getLocaleFromHost(host) },
+        query: {
+            locale: getLocaleFromQuery(query, config.routing.inbound.queryKey),
+        },
         cookie: { locale: cookie },
         detected: { locale: detected },
     });

package/dist/express/src/routing/inbound/resolve-locale/resolve-locale.js

@@ -1,23 +1,30 @@
+import '../../../core/error/intor-error.js';
+import { normalizeLocale } from '../../../core/utils/normalizers/normalize-locale.js';
+import 'logry';
+
 /**
- * Resolves the active locale from inbound routing configuration.
+ * Resolve the active locale from inbound routing configuration.
  *
- * The first matching locale from the configured sources is used,
- * with the detected locale as a guaranteed fallback.
+ * Iterates through configured locale sources and returns the first
+ * normalized, supported locale. Falls back to the detected locale
+ * or the default locale if none match.
  */
 function resolveLocale(config, context) {
     const { localeSources } = config.routing.inbound;
     for (const source of localeSources) {
         const locale = context[source]?.locale;
-        if (!locale)
+        const normalized = normalizeLocale(locale, config.supportedLocales);
+        if (!normalized)
             continue;
         return {
-            locale,
+            locale: normalized,
             localeSource: source,
         };
     }
     // Fallback: detected is always available
     return {
-        locale: context.detected.locale,
+        locale: normalizeLocale(context.detected.locale, config.supportedLocales) ||
+            config.defaultLocale,
         localeSource: "detected",
     };
 }

package/dist/express/src/routing/locale/get-locale-from-accept-language.js

@@ -1,29 +1,20 @@
-import '../../core/error/intor-error.js';
-import { normalizeLocale } from '../../core/utils/normalizers/normalize-locale.js';
-import 'logry';
-
 /**
- * Resolve locale from the `Accept-Language` header.
- *
- * - Parses language priorities (`q` values) from the header.
- * - Selects the highest-priority language supported by the application.
- * - Normalizes the matched locale against `supportedLocales`.
+ * Get locale candidate from the `Accept-Language` header.
  *
- * If no supported locale can be resolved, `undefined` is returned.
+ * Parses language priorities and returns the highest-priority
+ * language present in `supportedLocales`, without normalization.
  *
  * @example
  * ```ts
  * getLocaleFromAcceptLanguage("en-US,en;q=0.8,zh-TW;q=0.9", ["en-US", "zh-TW"])
  * // => "en-US"
+ *
  * getLocaleFromAcceptLanguage("fr,ja;q=0.9", ["en", "zh-TW"])
  * // => undefined
  * ```
  */
-const getLocaleFromAcceptLanguage = (config, acceptLanguageHeader) => {
-    const { supportedLocales } = config;
-    if (!acceptLanguageHeader ||
-        !supportedLocales ||
-        supportedLocales.length === 0) {
+const getLocaleFromAcceptLanguage = (acceptLanguageHeader, supportedLocales) => {
+    if (!acceptLanguageHeader || supportedLocales.length === 0) {
         return;
     }
     const supportedLocalesSet = new Set(supportedLocales);
@@ -41,7 +32,7 @@ const getLocaleFromAcceptLanguage = (config, acceptLanguageHeader) => {
     const sortedByPriority = parsedLanguages.toSorted((a, b) => b.q - a.q);
     // 3. Pick the first language explicitly supported
     const preferred = sortedByPriority.find(({ lang }) => supportedLocalesSet.has(lang))?.lang;
-    return normalizeLocale(preferred, supportedLocales);
+    return preferred;
 };
 
 export { getLocaleFromAcceptLanguage };

package/dist/express/src/routing/locale/get-locale-from-host.js

@@ -1,33 +1,32 @@
-import '../../core/error/intor-error.js';
-import { normalizeLocale } from '../../core/utils/normalizers/normalize-locale.js';
-import 'logry';
-
 /**
- * Extract locale from hostname.
+ * Get locale candidate from hostname.
  *
- * Only the left-most subdomain is considered as a locale candidate, if present.
+ * Returns the left-most hostname label, without validation or normalization.
  *
  * @example
  * ```ts
- * getLocaleFromHost(config, "en.example.com")
+ * getLocaleFromHost("en.example.com")
  * // => "en"
- * getLocaleFromHost(config, "example.com")
- * // => undefined
- * getLocaleFromHost(config, "api.jp.example.com")
+ *
+ * getLocaleFromHost("example.com")
+ * // => "example"
+ *
+ * getLocaleFromHost("api.jp.example.com")
+ * // => "api"
+ *
+ * getLocaleFromHost("localhost")
  * // => undefined
  * ```
  */
-function getLocaleFromHost(config, host) {
+function getLocaleFromHost(host) {
     if (!host)
         return;
-    const { supportedLocales } = config;
     // Remove port (e.g. localhost:3000)
     const hostname = host.split(":")[0];
     const parts = hostname.split(".");
     if (parts.length < 2)
         return;
-    const candidate = parts[0];
-    return normalizeLocale(candidate, supportedLocales);
+    return parts[0];
 }
 
 export { getLocaleFromHost };

package/dist/express/src/routing/locale/get-locale-from-pathname.js

@@ -3,19 +3,10 @@ import { normalizePathname } from '../../core/utils/normalizers/normalize-pathna
 import 'logry';
 
 /**
- * Extracts the locale from a pathname, if present.
+ * Get locale from pathname.
  *
- * - Normalizes the raw pathname.
- * - Strips the configured basePath.
- * - Inspects the first path segment to determine whether
- *   it matches a supported locale.
- *
- * If no locale segment is found, `undefined` is returned.
- *
- * Note:
- * - The pathname is treated as a canonical source.
- * - Only exact matches against `supportedLocales` are accepted.
- * - ___Locale normalization is intentionally not applied here.___
+ * Extracts the first pathname segment (after basePath) as a locale
+ * if it exactly matches one of the supported locales.
  *
  * @example
  * ```ts
@@ -31,7 +22,7 @@ import 'logry';
  * // => "en"
  * ```
  */
-function getLocaleFromPathname(config, pathname) {
+function getLocaleFromPathname(pathname, config) {
     const { routing, supportedLocales } = config;
     const { basePath } = routing;
     // 1. Normalize pathname

package/dist/express/src/routing/locale/get-locale-from-query.js

@@ -1,35 +1,29 @@
-import '../../core/error/intor-error.js';
-import { normalizeLocale } from '../../core/utils/normalizers/normalize-locale.js';
-import 'logry';
-
 /**
- * Extracts locale from URL query parameters.
- *
- * - Reads the configured locale query key.
- * - Normalizes the value against supported locales.
+ * Get locale candidate from URL query parameters.
  *
- * If no valid locale is found, `undefined` is returned.
+ * Extracts the value of the configured query key, without
+ * validation or normalization.
  *
  * @example
  * ```ts
- * getLocaleFromQuery(config, { locale: "en" })
+ * getLocaleFromQuery({ locale: "en" }, "locale")
  * // => "en"
- * getLocaleFromQuery(config, {})
+ *
+ * getLocaleFromQuery({}, "locale")
  * // => undefined
- * getLocaleFromQuery(config, { locale: ["zh-TW"] })
+ *
+ * getLocaleFromQuery({ locale: ["zh-TW"] }, "locale")
  * // => "zh-TW"
  * ```
  */
-function getLocaleFromQuery(config, query) {
+function getLocaleFromQuery(query, queryKey) {
     if (!query)
         return;
-    const { supportedLocales, routing } = config;
-    const { queryKey } = routing.inbound;
     const raw = query[queryKey];
     if (!raw)
         return;
     const value = Array.isArray(raw) ? raw[0] : raw;
-    return normalizeLocale(value, supportedLocales);
+    return value;
 }
 
 export { getLocaleFromQuery };