intor 2.3.4 → 2.3.5

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

@@ -0,0 +1,77 @@
+import { loadLocalMessages } from './load-local-messages/load-local-messages.js';
+import { loadRemoteMessages } from './load-remote-messages/load-remote-messages.js';
+import { getLogger } from '../shared/logger/get-logger.js';
+
+/**
+ * Load locale messages based on the resolved Intor configuration.
+ *
+ * This function acts as a thin orchestration layer that:
+ *
+ * - Selects the appropriate message loader (local or remote)
+ * - Applies fallback locale resolution
+ * - Delegates caching and concurrency behavior to the underlying loader
+ *
+ * It does not perform message normalization or transformation itself.
+ */
+const loadMessages = async ({ config, locale, extraOptions: { exts, messagesReader } = {}, allowCacheWrite = false, }) => {
+    const baseLogger = getLogger({ id: config.id, ...config.logger });
+    const logger = baseLogger.child({ scope: "load-messages" });
+    // Guard: no loader configured
+    if (!config.loader) {
+        logger.warn("No loader options have been configured in the current config.");
+        return;
+    }
+    const { type, concurrency, rootDir, namespaces } = config.loader;
+    const fallbackLocales = config.fallbackLocales[locale] || [];
+    logger.info(`Loading messages for locale "${locale}".`);
+    logger.trace("Starting to load messages with runtime context.", {
+        loaderType: type,
+        locale,
+        fallbackLocales,
+        namespaces: namespaces && namespaces.length > 0 ? [...namespaces] : "[ALL]",
+        cache: config.cache,
+        concurrency: concurrency ?? 10,
+    });
+    let loadedMessages;
+    // --- loader type: local
+    if (type === "local") {
+        loadedMessages = await loadLocalMessages({
+            locale,
+            fallbackLocales,
+            namespaces,
+            rootDir,
+            extraOptions: {
+                concurrency,
+                cacheOptions: config.cache,
+                loggerOptions: { id: config.id, ...config.logger },
+                exts,
+                messagesReader,
+            },
+            allowCacheWrite,
+        });
+    }
+    // --- loader type: remote
+    else if (type === "remote") {
+        // Fetch messages from remote
+        loadedMessages = await loadRemoteMessages({
+            locale,
+            fallbackLocales,
+            namespaces,
+            rootDir,
+            remoteUrl: config.loader.remoteUrl,
+            remoteHeaders: config.loader.remoteHeaders,
+            extraOptions: {
+                cacheOptions: config.cache,
+                loggerOptions: { id: config.id, ...config.logger },
+            },
+            allowCacheWrite,
+        });
+    }
+    // No messages found
+    if (!loadedMessages || Object.keys(loadedMessages).length === 0) {
+        logger.warn("No messages found.", { locale, fallbackLocales, namespaces });
+    }
+    return loadedMessages;
+};
+
+export { loadMessages };

package/dist/next/src/server/messages/load-remote-messages/fetch-locale-messages/fetch-locale-messages.js

@@ -0,0 +1,55 @@
+import { isValidMessages } from '../../shared/utils/is-valid-messages.js';
+import { getLogger } from '../../../shared/logger/get-logger.js';
+
+/**
+ * Fetches locale messages from a remote API.
+ *
+ * - Validates that the returned JSON matches the expected `NamespaceMessages` structure.
+ * - Uses `fetch` with `no-store` cache to always get fresh data.
+ */
+const fetchLocaleMessages = async ({ remoteUrl, remoteHeaders, searchParams, locale, extraOptions: { loggerOptions } = {}, signal, }) => {
+    const baseLogger = getLogger({ ...loggerOptions });
+    const logger = baseLogger.child({ scope: "fetch-locale-messages" });
+    try {
+        const params = new URLSearchParams(searchParams);
+        params.append("locale", locale);
+        const url = `${remoteUrl}?${params.toString()}`;
+        // Headers
+        const headers = {
+            "Content-Type": "application/json",
+            ...remoteHeaders,
+        };
+        // Fetch
+        const response = await fetch(url, {
+            method: "GET",
+            headers,
+            cache: "no-store",
+            signal,
+        });
+        if (!response.ok) {
+            throw new Error(`HTTP error ${response.status} ${response.statusText}`);
+        }
+        // Parse JSON body
+        const data = (await response.json());
+        // Validate messages structure
+        if (!isValidMessages(data[locale])) {
+            throw new Error("JSON file does not match NamespaceMessages structure");
+        }
+        return data;
+    }
+    catch (error) {
+        if (error instanceof Error && error.name === "AbortError") {
+            logger.debug("Fetching locale messages aborted.", { locale, remoteUrl });
+            return;
+        }
+        logger.warn("Fetching locale messages failed.", {
+            locale,
+            remoteUrl,
+            searchParams: decodeURIComponent(searchParams.toString()),
+            error,
+        });
+        return;
+    }
+};
+
+export { fetchLocaleMessages };

package/dist/next/src/server/messages/load-remote-messages/fetch-locale-messages/utils/build-search-params.js

@@ -0,0 +1,25 @@
+/**
+ * Build URLSearchParams from an object.
+ * Supports string or string[] values. Ignores undefined/null.
+ */
+const buildSearchParams = (params) => {
+    const searchParams = new URLSearchParams();
+    const appendParam = (key, value) => {
+        if (value === undefined || value === null)
+            return;
+        if (Array.isArray(value) && value.length === 0)
+            return;
+        if (Array.isArray(value)) {
+            value.forEach((v) => v && searchParams.append(key, v));
+        }
+        else {
+            searchParams.append(key, value);
+        }
+    };
+    Object.entries(params).forEach(([key, value]) => {
+        appendParam(key, value);
+    });
+    return searchParams;
+};
+
+export { buildSearchParams };

package/dist/next/src/server/messages/load-remote-messages/load-remote-messages.js

@@ -0,0 +1,110 @@
+import { DEFAULT_CACHE_OPTIONS } from '../../../config/constants/cache.constants.js';
+import { fetchLocaleMessages } from './fetch-locale-messages/fetch-locale-messages.js';
+import { buildSearchParams } from './fetch-locale-messages/utils/build-search-params.js';
+import { getLogger } from '../../shared/logger/get-logger.js';
+import { getGlobalMessagesPool } from '../../shared/messages/global-messages-pool.js';
+import { normalizeCacheKey } from '../../../shared/utils/normalizers/normalize-cache-key.js';
+
+/**
+ * Load locale messages from a remote API.
+ *
+ * This function acts as the orchestration layer for remote message loading.
+ * It is responsible for:
+ *
+ * - Resolving fallback locales in order
+ * - Coordinating cache read / write behavior
+ * - Respecting abort signals across the entire async flow
+ *
+ * Network fetching and data validation are delegated to lower-level utilities.
+ */
+const loadRemoteMessages = async ({ pool = getGlobalMessagesPool(), rootDir, locale, fallbackLocales, namespaces, remoteUrl, remoteHeaders, extraOptions: { cacheOptions = DEFAULT_CACHE_OPTIONS, loggerOptions = { id: "default" }, } = {}, allowCacheWrite = false, signal, }) => {
+    const baseLogger = getLogger({ ...loggerOptions });
+    const logger = baseLogger.child({ scope: "load-remote-messages" });
+    // Abort early if the request has already been cancelled
+    if (signal?.aborted) {
+        logger.debug("Remote message loading aborted before fetch.");
+        return;
+    }
+    const start = performance.now();
+    logger.debug("Loading remote messages.", { remoteUrl });
+    // --- Cache key
+    const cacheKey = normalizeCacheKey([
+        loggerOptions.id,
+        "loaderType:remote",
+        rootDir,
+        locale,
+        (fallbackLocales ?? []).toSorted().join(","),
+        (namespaces ?? []).toSorted().join(","),
+    ]);
+    // --- Cache read --------------------------------------------------
+    if (cacheOptions.enabled && cacheKey) {
+        const cached = await pool?.get(cacheKey);
+        if (signal?.aborted) {
+            logger.debug("Remote message loading aborted after cache read.");
+            return;
+        }
+        if (cached) {
+            logger.debug("Messages cache hit.", { key: cacheKey });
+            return cached;
+        }
+    }
+    const candidateLocales = [locale, ...(fallbackLocales || [])];
+    let messages;
+    // Try each candidate locale in order and stop at the first successful result
+    for (let i = 0; i < candidateLocales.length; i++) {
+        const candidateLocale = candidateLocales[i];
+        const isLast = i === candidateLocales.length - 1;
+        try {
+            const fetched = await fetchLocaleMessages({
+                remoteUrl,
+                remoteHeaders,
+                locale: candidateLocale,
+                searchParams: buildSearchParams({ rootDir, namespaces }),
+                extraOptions: { loggerOptions },
+                signal,
+            });
+            // Stop at the first locale that yields non-empty messages
+            if (fetched && Object.values(fetched[candidateLocale] || {}).length > 0) {
+                messages = fetched;
+                break;
+            }
+        }
+        catch (error) {
+            if (error instanceof Error && error.name === "AbortError") {
+                logger.debug("Remote message loading aborted.");
+                return;
+            }
+            if (isLast) {
+                logger.warn("Failed to load messages for all candidate locales.", {
+                    locale,
+                    fallbackLocales,
+                });
+            }
+            else {
+                logger.warn(`Failed to fetch locale messages for "${candidateLocale}", trying next fallback.`);
+            }
+            logger.trace("Remote fetch error detail.", {
+                locale: candidateLocale,
+                error,
+            });
+        }
+    }
+    // --- Cache write --------------------------------------------------
+    if (cacheOptions.enabled && allowCacheWrite && cacheKey && messages) {
+        if (signal?.aborted) {
+            logger.debug("Remote message loading aborted before cache write.");
+            return;
+        }
+        await pool?.set(cacheKey, messages, cacheOptions.ttl);
+    }
+    // Final success log with resolved locale and timing
+    if (messages) {
+        logger.trace("Finished loading remote messages.", {
+            loadedLocale: messages ? Object.keys(messages)[0] : undefined,
+            duration: `${Math.round(performance.now() - start)} ms`,
+        });
+    }
+    return messages;
+};
+
+export { loadRemoteMessages };

package/dist/next/src/server/messages/shared/utils/is-valid-messages.js

@@ -0,0 +1,36 @@
+/** Check if a value is a plain object (not null, not array) */
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * Check if a value is a valid **Messages** object.
+ *
+ * - Uses an iterative approach to avoid stack overflow with deeply nested objects.
+ *
+ * @example
+ * ```ts
+ * isValidMessages({ en: { hello: "Hello" } }) // true
+ * isValidMessages({ en: { count: 5 } }) // false
+ * ```
+ */
+function isValidMessages(value) {
+    if (!isPlainObject(value))
+        return false;
+    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);
+            }
+            else {
+                return false;
+            }
+        }
+    }
+    return true;
+}
+
+export { isPlainObject, isValidMessages };

package/dist/next/src/server/shared/logger/get-logger.js

@@ -0,0 +1,39 @@
+import { logry } from 'logry';
+import { getGlobalLoggerPool } from './global-logger-pool.js';
+
+const DEFAULT_FORMAT_CONFIG = {
+    timestamp: { withDate: false },
+};
+const DEFAULT_RENDER_CONFIG = {
+    timestamp: {},
+    id: { visible: true, prefix: "<", suffix: ">" },
+    meta: { lineBreaksAfter: 1 },
+};
+/**
+ * Get a shared logger instance by id.
+ * - Safe across hot reloads
+ * - Prevents unbounded memory usage via soft LRU
+ */
+function getLogger({ id = "default", formatConfig, renderConfig, preset, ...options }) {
+    const pool = getGlobalLoggerPool();
+    let logger = pool.get(id);
+    if (!logger) {
+        logger = logry({
+            id,
+            formatConfig: !formatConfig && !preset ? DEFAULT_FORMAT_CONFIG : formatConfig,
+            renderConfig: !renderConfig && !preset ? DEFAULT_RENDER_CONFIG : renderConfig,
+            preset,
+            ...options,
+        });
+        pool.set(id, logger);
+        // Soft LRU: keep pool size under control
+        if (pool.size > 1000) {
+            const keys = [...pool.keys()];
+            for (const key of keys.slice(0, 200))
+                pool.delete(key);
+        }
+    }
+    return logger;
+}
+
+export { getLogger };

package/dist/next/src/server/translator/get-translator.js

@@ -0,0 +1,35 @@
+import { Translator } from 'intor-translator';
+import { loadMessages } from '../messages/load-messages.js';
+
+// Implementation
+async function getTranslator(options) {
+    const { config, locale, preKey } = options;
+    const messages = await loadMessages({
+        config,
+        locale,
+        extraOptions: options.extraOptions,
+    });
+    // Create a Translator instance
+    const translator = new Translator({
+        locale,
+        messages,
+        fallbackLocales: config.fallbackLocales,
+        loadingMessage: config.translator?.loadingMessage,
+        placeholder: config.translator?.placeholder,
+        handlers: options.handlers,
+        plugins: options.plugins,
+    });
+    const props = { messages, locale };
+    const scoped = translator.scoped(preKey);
+    return {
+        ...props,
+        hasKey: preKey ? scoped.hasKey : translator.hasKey,
+        t: preKey ? scoped.t : translator.t,
+        // NOTE:
+        // Return type is fully validated by overload signatures.
+        // Assertion here is intentional due to TS inference limitations.
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    };
+}
+
+export { getTranslator };

package/dist/next/src/shared/constants/prefix-placeholder.js

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

package/dist/next/src/shared/utils/deep-merge.js

@@ -0,0 +1,36 @@
+/**
+ * Deeply merges two objects.
+ * - Nested objects → merged recursively
+ * - Array / primitive → b overwrites a
+ */
+const deepMerge = (a, b) => {
+    if (!a && !b)
+        return undefined;
+    if (!a)
+        return b;
+    if (!b)
+        return a;
+    const result = { ...a };
+    for (const key in b) {
+        if (Object.prototype.hasOwnProperty.call(b, key)) {
+            const av = a[key];
+            const bv = b[key];
+            if (av &&
+                bv &&
+                typeof av === "object" &&
+                typeof bv === "object" &&
+                !Array.isArray(av) &&
+                !Array.isArray(bv)) {
+                // recursive merge
+                result[key] = deepMerge(av, bv);
+            }
+            else {
+                // overwrite with primitive or array
+                result[key] = bv;
+            }
+        }
+    }
+    return result;
+};
+
+export { deepMerge };

package/dist/next/src/shared/utils/normalizers/normalize-cache-key.js

@@ -0,0 +1,45 @@
+const CACHE_KEY_DELIMITER = "|";
+const sanitize = (k) => k
+    .replaceAll(/[\u200B-\u200D\uFEFF]/g, "")
+    .replaceAll(/[\r\n]/g, "")
+    .trim();
+/**
+ * Normalizes a value into a stable cache key string.
+ *
+ * - Supports primitive values and structured array keys.
+ * - Produces deterministic output suitable for cache identifiers.
+ *
+ * Notes:
+ * - `null`, `undefined`, or empty arrays return `null`.
+ * - Special tokens are used for boolean, null, and undefined values
+ *   to preserve semantic differences.
+ */
+const normalizeCacheKey = (key, delimiter = CACHE_KEY_DELIMITER) => {
+    // Treat nullish values as "no cache key"
+    if (key === null || key === undefined)
+        return null;
+    if (Array.isArray(key)) {
+        // Empty array produces no meaningful cache key
+        if (key.length === 0)
+            return null;
+        const normalized = key.map((k) => {
+            // Preserve semantic differences for special values
+            if (k === null)
+                return "__null";
+            if (k === undefined)
+                return "__undefined";
+            if (typeof k === "boolean")
+                return k ? "__true" : "__false";
+            return sanitize(String(k));
+        });
+        // Join segments into a single deterministic cache key
+        return normalized.join(delimiter);
+    }
+    // Normalize boolean primitives explicitly
+    if (typeof key === "boolean")
+        return key ? "__true" : "__false";
+    // Fallback: stringify primitive values
+    return String(key);
+};
+
+export { normalizeCacheKey };

package/dist/next/src/shared/utils/normalizers/normalize-pathname.js

@@ -0,0 +1,43 @@
+/**
+ * Normalize a raw pathname string to ensure consistent formatting.
+ *
+ * - Trims leading and trailing whitespace (code points ≤ 32).
+ * - Collapses consecutive slashes into a single slash.
+ * - Ensures a single leading slash and removes redundant trailing slashes.
+ * - Optionally removes the leading slash.
+ * - Avoids intermediate array allocations for performance.
+ */
+const normalizePathname = (rawPathname, options = {}) => {
+    const length = rawPathname.length;
+    let start = 0;
+    let end = length - 1;
+    // Trim leading whitespace
+    while (start <= end && (rawPathname.codePointAt(start) ?? 0) <= 32)
+        start++;
+    // Trim trailing whitespace
+    while (end >= start && (rawPathname.codePointAt(end) ?? 0) <= 32)
+        end--;
+    if (start > end)
+        return "/"; // Only whitespace
+    let result = "";
+    let hasSlash = false;
+    for (let i = start; i <= end; i++) {
+        const char = rawPathname[i];
+        if (char === "/") {
+            if (!hasSlash) {
+                hasSlash = true;
+            }
+        }
+        else {
+            result += hasSlash || result === "" ? "/" + char : char;
+            hasSlash = false;
+        }
+    }
+    // If the result has a leading slash and we want to remove it, do so
+    if (options.removeLeadingSlash && result.startsWith("/")) {
+        result = result.slice(1);
+    }
+    return result || "/";
+};
+
+export { normalizePathname };

package/dist/next/src/shared/utils/pathname/get-unprefixed-pathname.js

@@ -0,0 +1,39 @@
+import { normalizePathname } from '../normalizers/normalize-pathname.js';
+
+/**
+ * Returns a canonical, locale-agnostic pathname.
+ *
+ * @example
+ * ```ts
+ * // config.supportedLocales: ["en-US"]
+ * // config.routing.basePath: "/app"
+ * // config.routing.prefix: "all"
+ * getUnprefixedPathname(config, "/app/en-US/about" );
+ * // => "/about"
+ *```
+ */
+function getUnprefixedPathname(config, rawPathname) {
+    const { routing, supportedLocales } = config;
+    const { basePath } = routing;
+    // 1. Normalize pathname
+    const normalizedPathname = normalizePathname(rawPathname);
+    // 2. Strip basePath
+    let prefixedPathname = normalizedPathname;
+    if (basePath && normalizedPathname === basePath) {
+        prefixedPathname = "/";
+    }
+    else if (basePath && normalizedPathname.startsWith(basePath + "/")) {
+        prefixedPathname = normalizedPathname.slice(basePath.length);
+    }
+    // 3. Detect locale segment
+    const firstSegment = prefixedPathname.split("/").find(Boolean);
+    const locale = firstSegment && supportedLocales.includes(firstSegment)
+        ? firstSegment
+        : undefined;
+    // 4. Strip locale segment
+    return locale
+        ? prefixedPathname.slice(locale.length + 1) || "/"
+        : prefixedPathname;
+}
+
+export { getUnprefixedPathname };

package/dist/next/src/shared/utils/pathname/locale-prefix-pathname.js

@@ -0,0 +1,38 @@
+import { PREFIX_PLACEHOLDER } from '../../constants/prefix-placeholder.js';
+import { normalizePathname } from '../normalizers/normalize-pathname.js';
+
+/**
+ * Applies routing prefix strategy by resolving the locale placeholder.
+ *
+ * @example
+ * ```ts
+ * // config.routing.prefix: "all"
+ * localePrefixPathname({ config, pathname: "/app/{locale}/about", locale: "en-US" });
+ * // => /app/en-US/about
+ *
+ * // config.routing.prefix: "none"
+ * localePrefixPathname({ config, pathname: "/app/{locale}/about", locale: "en-US" });
+ * // => /app/about
+ * ```
+ */
+const localePrefixPathname = (config, standardizedPathname, locale) => {
+    const { routing } = config;
+    const { prefix } = routing;
+    if (prefix !== "none" && !locale) {
+        throw new Error('No locale when using prefix "all", "except-default"');
+    }
+    // prefix: "all"
+    if (prefix === "all") {
+        return normalizePathname(standardizedPathname.replaceAll(PREFIX_PLACEHOLDER, locale));
+    }
+    // prefix: "except-default"
+    if (prefix === "except-default") {
+        return locale === config.defaultLocale
+            ? normalizePathname(standardizedPathname.replaceAll(`/${PREFIX_PLACEHOLDER}`, ""))
+            : normalizePathname(standardizedPathname.replaceAll(PREFIX_PLACEHOLDER, locale));
+    }
+    // prefix: "none"
+    return normalizePathname(standardizedPathname.replaceAll(`/${PREFIX_PLACEHOLDER}`, ""));
+};
+
+export { localePrefixPathname };

package/dist/next/src/shared/utils/pathname/localize-pathname.js

@@ -0,0 +1,36 @@
+import { getUnprefixedPathname } from './get-unprefixed-pathname.js';
+import { localePrefixPathname } from './locale-prefix-pathname.js';
+import { standardizePathname } from './standardize-pathname.js';
+
+/**
+ * Localizes a pathname by composing canonicalization,
+ * standardization, and locale prefix strategies.
+ *
+ * @example
+ * ```ts
+ * // config.supportedLocales: ["en-US"]
+ * // config.routing.basePath: "/app"
+ * // config.routing.prefix: "all"
+ * localePrefixPathname({ config, pathname: "/app/en-US/about", locale: "en-US" });
+ * // => {
+ * //   unprefixedPathname: '/about',
+ * //   standardizedPathname: '/app/{locale}/about',
+ * //   localizedPathname: '/app/en-US/about'
+ * // }
+ * ```
+ */
+const localizePathname = (config, rawPathname, locale) => {
+    // 1. Canonicalize: extract basePath and strip locale
+    const unprefixedPathname = getUnprefixedPathname(config, rawPathname);
+    // 2. Standardize: build a pathname with locale placeholder
+    const standardizedPathname = standardizePathname(config, unprefixedPathname);
+    // 3. Apply strategy: resolve locale prefix based on routing rules
+    const localizedPathname = localePrefixPathname(config, standardizedPathname, locale);
+    return {
+        unprefixedPathname,
+        standardizedPathname,
+        localizedPathname,
+    };
+};
+
+export { localizePathname };

package/dist/next/src/shared/utils/pathname/standardize-pathname.js

@@ -0,0 +1,30 @@
+import { PREFIX_PLACEHOLDER } from '../../constants/prefix-placeholder.js';
+import { normalizePathname } from '../normalizers/normalize-pathname.js';
+
+/**
+ * Standardizes a canonical pathname by applying the base path
+ * and injecting the locale placeholder.
+ *
+ * @example
+ * ```ts
+ * // routing.basePath: "/app",
+ * standardizePathname({ config, pathname: "/cms" });
+ * // => "/app/{locale}/cms"
+ * ```
+ */
+const standardizePathname = (config, unprefixedPathname) => {
+    const { routing } = config;
+    const { basePath } = routing;
+    // Normalize each segment before join to avoid redundant slashes
+    const parts = [
+        normalizePathname(basePath),
+        PREFIX_PLACEHOLDER,
+        normalizePathname(unprefixedPathname),
+    ];
+    // 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 };