intor 2.3.35 → 2.4.1

package/dist/fastify/src/routing/pathname/standardize-pathname.js

@@ -0,0 +1,34 @@
+import { PREFIX_PLACEHOLDER } from '../../core/constants/prefix-placeholder.js';
+import '../../core/error/intor-error.js';
+import { normalizePathname } from '../../core/utils/normalizers/normalize-pathname.js';
+import 'logry';
+import 'p-limit';
+import 'intor-translator';
+
+/**
+ * Standardizes a canonical pathname into an internal routing template
+ * by applying the base path and injecting a locale placeholder.
+ *
+ * @example
+ * ```ts
+ * // config.routing.basePath: "/app",
+ * // config.routing.prefix: "all"
+ * standardizePathname("/about", config);
+ * // => "/app/{locale}/about"
+ * ```
+ */
+const standardizePathname = (canonicalizedPathname, config) => {
+    const { basePath } = config.routing;
+    // Normalize each segment before join to avoid redundant slashes
+    const parts = [
+        normalizePathname(basePath),
+        PREFIX_PLACEHOLDER,
+        normalizePathname(canonicalizedPathname),
+    ];
+    // Avoid double slashes between segments
+    const standardizedPathname = parts.join("/").replaceAll(/\/{2,}/g, "/");
+    // Final normalization to ensure leading slash, no trailing
+    return normalizePathname(standardizedPathname);
+};
+
+export { standardizePathname };

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

@@ -0,0 +1,31 @@
+import '../../core/error/intor-error.js';
+import 'logry';
+import 'p-limit';
+import 'intor-translator';
+import { createTRich } from '../../core/translator/create-t-rich.js';
+import { initTranslator } from '../translator/init-translator.js';
+
+/**
+ * Get a server-side translator for the current execution context.
+ */
+async function getTranslator(config, params) {
+    const { locale, readers, allowCacheWrite, fetch, preKey, handlers, plugins } = params;
+    // Initialize a locale-bound translator snapshot with messages loaded
+    const translator = await initTranslator(config, locale, {
+        readers,
+        allowCacheWrite,
+        fetch: fetch || globalThis.fetch,
+        plugins,
+        handlers,
+    });
+    const scoped = translator.scoped(preKey);
+    return {
+        messages: translator.messages,
+        locale: translator.locale,
+        hasKey: scoped.hasKey,
+        t: scoped.t,
+        tRich: createTRich(scoped.t),
+    };
+}
+
+export { getTranslator };

package/dist/fastify/src/server/messages/load-local-messages/cache/messages-pool.js

@@ -0,0 +1,11 @@
+/**
+ * Get the messages pool.
+ */
+function getMessagesPool() {
+    if (!globalThis.__INTOR_MESSAGES_POOL__) {
+        globalThis.__INTOR_MESSAGES_POOL__ = new Map();
+    }
+    return globalThis.__INTOR_MESSAGES_POOL__;
+}
+
+export { getMessagesPool };

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

@@ -0,0 +1,108 @@
+import path from 'node:path';
+import pLimit from 'p-limit';
+import '../../../core/error/intor-error.js';
+import { normalizeCacheKey } from '../../../core/utils/normalizers/normalize-cache-key.js';
+import { getLogger } from '../../../core/logger/get-logger.js';
+import 'intor-translator';
+import { getMessagesPool } from './cache/messages-pool.js';
+import { readLocaleMessages } from './read-locale-messages/read-locale-messages.js';
+
+/**
+ * Load locale messages from the local file system.
+ *
+ * This function serves as the orchestration layer for local message loading.
+ * It coordinates:
+ *
+ * - Locale resolution with fallbacks
+ * - Concurrency control for file system access
+ * - Process-level memoization (read by default, write by ownership)
+ *
+ * Local messages are cached for the lifetime of the process.
+ * Cache writes are restricted to the primary initialization flow.
+ *
+ * File traversal, parsing, and validation are delegated to lower-level utilities.
+ */
+const loadLocalMessages = async ({ id, locale, fallbackLocales, namespaces, rootDir = "messages", concurrency = 10, readers, pool = getMessagesPool(), allowCacheWrite = false, loggerOptions, }) => {
+    const baseLogger = getLogger(loggerOptions);
+    const logger = baseLogger.child({ scope: "load-local-messages" });
+    const start = performance.now();
+    logger.debug("Loading local messages.", {
+        rootDir,
+        resolvedRootDir: path.resolve(rootDir),
+    });
+    // ---------------------------------------------------------------------------
+    // Cache key resolution
+    // ---------------------------------------------------------------------------
+    const cacheKey = normalizeCacheKey([
+        id,
+        "loaderType:local",
+        rootDir,
+        locale,
+        fallbackLocales?.toSorted().join(","),
+        namespaces?.toSorted().join(","),
+    ].filter(Boolean));
+    // ---------------------------------------------------------------------------
+    // Cache read
+    // ---------------------------------------------------------------------------
+    if (cacheKey) {
+        const cached = pool.get(cacheKey);
+        if (cached) {
+            logger.debug("Messages cache hit.", { key: cacheKey });
+            return cached;
+        }
+    }
+    // ---------------------------------------------------------------------------
+    // Resolve locale messages with ordered fallback strategy
+    // ---------------------------------------------------------------------------
+    const limit = pLimit(concurrency);
+    const candidateLocales = [locale, ...(fallbackLocales || [])];
+    let messages;
+    for (let i = 0; i < candidateLocales.length; i++) {
+        const candidateLocale = candidateLocales[i];
+        const isLast = i === candidateLocales.length - 1;
+        try {
+            const result = await readLocaleMessages({
+                locale: candidateLocale,
+                namespaces,
+                rootDir,
+                limit,
+                readers,
+                loggerOptions,
+            });
+            // Stop at the first locale that yields non-empty messages
+            if (Object.values(result[candidateLocale] || {}).length > 0) {
+                messages = result;
+                break;
+            }
+        }
+        catch {
+            if (isLast) {
+                logger.warn("Failed to load messages for all candidate locales.", {
+                    locale,
+                    fallbackLocales,
+                });
+            }
+            else {
+                logger.warn(`Failed to load locale messages for "${candidateLocale}", trying next fallback.`);
+            }
+        }
+    }
+    // ---------------------------------------------------------------------------
+    // Cache write (explicitly permitted)
+    // ---------------------------------------------------------------------------
+    const isProd = process.env.NODE_ENV === "production";
+    const canWriteCache = isProd && allowCacheWrite;
+    if (canWriteCache && cacheKey && messages) {
+        pool.set(cacheKey, messages);
+    }
+    // Final success log with resolved locale and timing
+    if (messages) {
+        logger.trace("Finished loading local messages.", {
+            loadedLocale: Object.keys(messages)[0],
+            duration: `${Math.round(performance.now() - start)} ms`,
+        });
+    }
+    return messages;
+};
+
+export { loadLocalMessages };

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

@@ -0,0 +1,91 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import '../../../../../core/error/intor-error.js';
+import { getLogger } from '../../../../../core/logger/get-logger.js';
+import 'p-limit';
+import 'intor-translator';
+
+/**
+ * Recursively collects message file metadata under a given locale root.
+ *
+ * - Traverses directories and collects matching message files
+ * - Supports filtering by file extensions and optional namespaces
+ *
+ * @example
+ * ```ts
+ * [{
+ *     namespace: "auth", // If messages under locale root (no namespace) -> "index"
+ *     fullPath: "/Users/john/my-app/messages/en-US/auth/login.json",
+ *     relativePath: "auth/login.json",
+ *     segments: ["auth", "login"],
+ *     basename: "login",
+ * }, ... ];
+ * ```
+ */
+async function collectFileEntries({ readdir = fs.readdir, namespaces, rootDir, limit, exts = [], 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) => {
+        // -------------------------------------------------------------------------
+        // Read directory entries
+        // -------------------------------------------------------------------------
+        let entries = [];
+        try {
+            entries = await readdir(currentDir, { withFileTypes: true });
+        }
+        catch {
+            logger.debug("Locale directory not found, skipping locale.", {
+                localeDir: currentDir,
+            });
+            return;
+        }
+        // -------------------------------------------------------------------------
+        // 1. Recurse into sub-directories (control flow, no limit)
+        // -------------------------------------------------------------------------
+        for (const entry of entries) {
+            if (!entry.isDirectory())
+                continue;
+            await walk(path.join(currentDir, entry.name));
+        }
+        // -------------------------------------------------------------------------
+        // 2. Process files (IO-bound, concurrency-limited)
+        // -------------------------------------------------------------------------
+        const tasks = entries
+            .filter((entry) => entry.isFile())
+            .map((entry) => limit(async () => {
+            const fullPath = path.join(currentDir, entry.name);
+            const ext = path.extname(entry.name).slice(1);
+            if (!ext || !supportedExts.has(ext))
+                return;
+            const relativePath = path.relative(rootDir, fullPath);
+            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)
+                return;
+            // Apply namespace filter (always allow "index")
+            if (namespaces && namespace !== "index") {
+                if (!namespaces.includes(namespace))
+                    return;
+            }
+            fileEntries.push({
+                namespace,
+                fullPath,
+                relativePath,
+                segments,
+                basename: path.basename(entry.name, `.${ext}`),
+            });
+        }));
+        await Promise.all(tasks);
+    };
+    await walk(rootDir);
+    if (fileEntries.length > 0) {
+        logger.trace(`Collected ${fileEntries.length} local message files for locale "${path.basename(rootDir)}".`);
+    }
+    return fileEntries;
+}
+
+export { collectFileEntries };

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

@@ -0,0 +1,103 @@
+import path from 'node:path';
+import '../../../../../core/error/intor-error.js';
+import { deepMerge } from '../../../../../core/utils/deep-merge.js';
+import { getLogger } from '../../../../../core/logger/get-logger.js';
+import 'p-limit';
+import { isValidMessages } from '../../../../../core/messages/utils/is-valid-messages.js';
+import { nestObjectFromPath } from '../../../../../core/messages/utils/nest-object-from-path.js';
+import 'intor-translator';
+import { jsonReader } from './utils/json-reader.js';
+
+/**
+ * Parse locale message files into a unified Messages object (single-locale).
+ *
+ * - Reads JSON or custom formats (via `messagesReader`)
+ * - Validates message structure
+ * - Builds nested objects based on file path segments
+ * - Deep-merges entries by namespace
+ *
+ * @example
+ * ```plain
+ * File paths:
+ *   - en/index.json        = { a: "A" }
+ *   - en/ui.json           = { b: "B" }
+ *   - en/auth/index.json   = { c: "C" }
+ *   - en/auth/verify.json  = { d: "D" }
+ *```
+
+ * The final return value is a `Messages` object:
+ * ```ts
+ * {
+ *   a: "A",
+ *   ui: { b: "B" },
+ *   auth: {
+ *     c: "C",
+ *     verify: { d: "D" },
+ *   },
+ * }
+ * ```
+ */
+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
+    const parsedFileEntries = [];
+    const tasks = fileEntries.map(({ namespace, segments, basename, fullPath }) => limit(async () => {
+        try {
+            // -------------------------------------------------------------------
+            // Read and validate file content
+            // -------------------------------------------------------------------
+            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");
+            }
+            // -------------------------------------------------------------------
+            // Build nested message object from path segments
+            // -------------------------------------------------------------------
+            const segmentsWithoutNamespace = segments.slice(1);
+            const isIndexFile = basename === "index";
+            const keyPath = isIndexFile
+                ? segmentsWithoutNamespace.slice(0, -1)
+                : segmentsWithoutNamespace;
+            // Nest the parsed content based on the path segments
+            const nestedMessages = nestObjectFromPath(keyPath, raw);
+            parsedFileEntries.push({ namespace, messages: nestedMessages });
+        }
+        catch (error) {
+            logger.warn("Failed to read or parse file.", {
+                path: fullPath,
+                error,
+            });
+        }
+    }));
+    await Promise.all(tasks);
+    // ---------------------------------------------------------------------------
+    // Merge parsed entries by namespace
+    // ---------------------------------------------------------------------------
+    const result = {};
+    for (const { namespace, messages } of parsedFileEntries) {
+        // Root-level namespace (e.g. [locale]/index.json)
+        if (namespace === "index") {
+            Object.assign(result, deepMerge(result, messages));
+        }
+        else {
+            result[namespace] = deepMerge(result[namespace], messages);
+        }
+    }
+    return result;
+}
+
+export { parseFileEntries };

package/dist/fastify/src/server/messages/load-local-messages/read-locale-messages/parse-file-entries/utils/json-reader.js

@@ -0,0 +1,12 @@
+import fs from 'node:fs/promises';
+
+/**
+ *  Read & parse a JSON file
+ */
+async function jsonReader(filePath, readFile = fs.readFile) {
+    const raw = await readFile(filePath, "utf8");
+    const parsed = JSON.parse(raw);
+    return parsed;
+}
+
+export { jsonReader };

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

@@ -0,0 +1,42 @@
+import path from 'node:path';
+import { collectFileEntries } from './collect-file-entries/collect-file-entries.js';
+import { parseFileEntries } from './parse-file-entries/parse-file-entries.js';
+
+/**
+ * Read and assemble messages for a single locale from the file system.
+ *
+ * This function acts as a thin orchestration layer:
+ * - Collects message file metadata for the locale
+ * - Parses files into a single Messages object
+ * - Wraps the result under the locale key
+ *
+ * It does not perform validation or transformation itself.
+ */
+const readLocaleMessages = async ({ locale, namespaces, rootDir = "messages", limit, readers, loggerOptions, }) => {
+    // ---------------------------------------------------------------------------
+    // Collect message file entries for the locale
+    // ---------------------------------------------------------------------------
+    const fileEntries = await collectFileEntries({
+        namespaces,
+        rootDir: path.resolve(rootDir, locale),
+        limit,
+        exts: Object.keys(readers || {}),
+        loggerOptions,
+    });
+    // ---------------------------------------------------------------------------
+    // Parse collected files into a Messages object (single-locale)
+    // ---------------------------------------------------------------------------
+    const messages = await parseFileEntries({
+        fileEntries,
+        limit,
+        readers,
+        loggerOptions,
+    });
+    // ---------------------------------------------------------------------------
+    // Wrap parsed messages under the locale key
+    // ---------------------------------------------------------------------------
+    const localeMessages = { [locale]: messages };
+    return localeMessages;
+};
+
+export { readLocaleMessages };

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

@@ -0,0 +1,78 @@
+import '../../core/error/intor-error.js';
+import { resolveLoaderOptions } from '../../core/utils/resolve-loader-options.js';
+import { getLogger } from '../../core/logger/get-logger.js';
+import { loadRemoteMessages } from '../../core/messages/load-remote-messages/load-remote-messages.js';
+import 'intor-translator';
+import { loadLocalMessages } from './load-local-messages/load-local-messages.js';
+
+/**
+ * Load locale messages according to the resolved Intor loader configuration.
+ *
+ * This function is the top-level orchestration entry for message loading.
+ * It is responsible for:
+ *
+ * - Resolving the active loader strategy (local or remote)
+ * - Dispatching to the appropriate loader implementation
+ * - Passing through cache and read-related options
+ *
+ * Message traversal, parsing, fallback resolution, and caching logic
+ * are delegated to the selected loader.
+ */
+const loadMessages = async ({ config, locale, readers, allowCacheWrite = false, fetch, }) => {
+    const baseLogger = getLogger(config.logger);
+    const logger = baseLogger.child({ scope: "load-messages" });
+    // ---------------------------------------------------------------------------
+    // Resolve loader configuration
+    // ---------------------------------------------------------------------------
+    const loader = resolveLoaderOptions(config);
+    if (!loader) {
+        logger.warn("No loader options have been configured in the current config.");
+        return;
+    }
+    const { mode, namespaces, concurrency } = loader;
+    const fallbackLocales = config.fallbackLocales[locale] || [];
+    logger.info(`Loading messages for locale "${locale}".`);
+    logger.trace("Starting to load messages with runtime context.", {
+        loaderMode: mode,
+        ...(mode === "local" ? { rootDir: loader.rootDir } : {}),
+        locale,
+        fallbackLocales: fallbackLocales.join(", "),
+        namespaces: namespaces && namespaces.length > 0 ? [...namespaces] : "*",
+    });
+    // ---------------------------------------------------------------------------
+    // Dispatch to loader implementation
+    // ---------------------------------------------------------------------------
+    let loadedMessages;
+    if (mode === "local") {
+        loadedMessages = await loadLocalMessages({
+            id: config.id,
+            locale,
+            fallbackLocales,
+            namespaces,
+            rootDir: loader.rootDir,
+            concurrency,
+            readers,
+            allowCacheWrite,
+            loggerOptions: config.logger,
+        });
+    }
+    else if (mode === "remote") {
+        loadedMessages = await loadRemoteMessages({
+            locale,
+            fallbackLocales,
+            namespaces,
+            concurrency,
+            fetch,
+            url: loader.url,
+            headers: loader.headers,
+            loggerOptions: config.logger,
+        });
+    }
+    // Final sanity check
+    if (!loadedMessages || Object.keys(loadedMessages).length === 0) {
+        logger.warn("No messages found.", { locale, fallbackLocales, namespaces });
+    }
+    return loadedMessages;
+};
+
+export { loadMessages };

package/dist/fastify/src/server/translator/init-translator.js

@@ -0,0 +1,36 @@
+import '../../core/error/intor-error.js';
+import { resolveLoaderOptions } from '../../core/utils/resolve-loader-options.js';
+import 'logry';
+import 'p-limit';
+import { createTranslator } from '../../core/translator/create-translator.js';
+import 'intor-translator';
+import { loadMessages } from '../messages/load-messages.js';
+import 'node:path';
+import 'node:fs/promises';
+
+/**
+ * Initialize a locale-bound Translator snapshot.
+ *
+ * - Resolves loader options and loads messages if configured
+ * - Creates an immutable Translator instance for server usage
+ */
+async function initTranslator(config, locale, options) {
+    const { readers, allowCacheWrite = false, fetch, handlers, plugins, } = options;
+    const loader = resolveLoaderOptions(config);
+    // Load messages
+    let messages = {};
+    if (loader) {
+        const loaded = await loadMessages({
+            config,
+            locale,
+            readers,
+            allowCacheWrite,
+            fetch,
+        });
+        messages = loaded || {};
+    }
+    // Create immutable translator snapshot
+    return createTranslator({ config, locale, messages, handlers, plugins });
+}
+
+export { initTranslator };

package/dist/hono/export/hono/index.js

@@ -0,0 +1,3 @@
+export { createIntorHandler } from '../../src/adapters/hono/create-intor-handler.js';
+export { getTranslator } from '../../src/adapters/hono/get-translator.js';
+import 'hono';

package/dist/hono/src/adapters/hono/create-intor-handler.js

@@ -0,0 +1,53 @@
+import '../../core/error/intor-error.js';
+import { parseCookieHeader } from '../../core/utils/parse-cookie-header.js';
+import { normalizeQuery } from '../../core/utils/normalizers/normalize-query.js';
+import 'logry';
+import 'p-limit';
+import 'intor-translator';
+import { getTranslator } from '../../edge/helpers/get-translator.js';
+import { resolveInbound } from '../../routing/inbound/resolve-inbound.js';
+import { getLocaleFromAcceptLanguage } from '../../routing/locale/get-locale-from-accept-language.js';
+
+/**
+ * Resolves locale-aware routing for the current execution context.
+ *
+ * - Binds resolved routing state to the request.
+ *
+ * @platform Hono
+ */
+function createIntorHandler(config, options) {
+    return async function intorHandler(c, next) {
+        // Locale from Accept-Language header
+        const acceptLanguage = c.req.header("accept-language");
+        const localeFromAcceptLanguage = getLocaleFromAcceptLanguage(acceptLanguage, config.supportedLocales);
+        // ----------------------------------------------------------
+        // Resolve inbound routing decision (pure computation)
+        // ----------------------------------------------------------
+        const url = new URL(c.req.url);
+        const { locale, localeSource, pathname } = await resolveInbound(config, url.pathname, {
+            host: url.hostname,
+            query: normalizeQuery(Object.fromEntries(url.searchParams)),
+            cookie: parseCookieHeader(c.req.header("cookie"))[config.cookie.name],
+            detected: localeFromAcceptLanguage || config.defaultLocale,
+        });
+        // --------------------------------------------------
+        // Bind inbound routing context
+        // --------------------------------------------------
+        c.set("intor", { locale, localeSource, pathname });
+        const { hasKey, t, tRich } = await getTranslator(config, {
+            locale,
+            handlers: options?.handlers,
+            plugins: options?.plugins,
+        });
+        // DX shortcuts (enabled by default)
+        if (options?.shortcuts !== false) {
+            c.set("locale", locale);
+            c.set("hasKey", hasKey);
+            c.set("t", t);
+            c.set("tRich", tRich);
+        }
+        await next();
+    };
+}
+
+export { createIntorHandler };

package/dist/hono/src/adapters/hono/get-translator.js

@@ -0,0 +1,20 @@
+import { getTranslator as getTranslator$1 } from '../../edge/helpers/get-translator.js';
+
+/**
+ * Get a edge-runtime translator for the current execution context.
+ *
+ * - Automatically resolves the locale from the framework context.
+ *
+ * @platform Hono
+ */
+async function getTranslator(config, c, params) {
+    const { preKey, handlers, plugins } = params || {};
+    return getTranslator$1(config, {
+        locale: c.get("intor")?.locale || config.defaultLocale,
+        preKey,
+        handlers,
+        plugins,
+    });
+}
+
+export { getTranslator };

package/dist/hono/src/core/constants/prefix-placeholder.js

@@ -0,0 +1,4 @@
+// Default prefix placeholder
+const PREFIX_PLACEHOLDER = "{locale}";
+
+export { PREFIX_PLACEHOLDER };

package/dist/hono/src/core/error/intor-error.js

@@ -0,0 +1,9 @@
+var IntorErrorCode;
+(function (IntorErrorCode) {
+    // config
+    IntorErrorCode["INVALID_CONFIG_ID"] = "INTOR_INVALID_CONFIG_ID";
+    IntorErrorCode["MISSING_SUPPORTED_LOCALES"] = "INTOR_MISSING_SUPPORTED_LOCALES";
+    IntorErrorCode["UNSUPPORTED_DEFAULT_LOCALE"] = "INTOR_UNSUPPORTED_DEFAULT_LOCALE";
+})(IntorErrorCode || (IntorErrorCode = {}));
+
+export { IntorErrorCode };