intor 2.3.6 → 2.3.7

package/dist/react/src/core/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/react/src/core/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 };

package/dist/react/src/core/utils/resolve-loader-options.js

@@ -0,0 +1,32 @@
+/**
+ * Resolve the effective message loader for a given runtime.
+ *
+ * Loader resolution follows an inheritance-based priority model:
+ *
+ * - client runtime:
+ *   client.loader → server.loader → root loader
+ *
+ * - server runtime:
+ *   server.loader → root loader
+ *
+ * This allows the client runtime to inherit server behavior
+ * when no explicit client loader is provided.
+ *
+ * Notes:
+ * - Static `messages` are intentionally NOT handled here.
+ * - Returning `undefined` indicates that no loader is enabled
+ *   for the given runtime.
+ */
+const resolveLoaderOptions = (config, runtime) => {
+    // --- runtime: client ---
+    {
+        const client = config.client?.loader;
+        if (client) {
+            // Client loader is always remote by design
+            return { type: "remote", ...client };
+        }
+        return config.server?.loader ?? config.loader;
+    }
+};
+
+export { resolveLoaderOptions };

package/dist/{next → react}/src/routing/resolve-navigation-target.js

@@ -1,5 +1,8 @@
-import { localizePathname } from '../shared/utils/pathname/localize-pathname.js';
-import { isExternalDestination } from '../shared/utils/is-external-destination.js';
+import '../core/error/intor-error.js';
+import { isExternalDestination } from '../core/utils/is-external-destination.js';
+import { localizePathname } from '../core/utils/pathname/localize-pathname.js';
+import 'logry';
+import 'keyv';
 
 /**
  * Resolves the destination of a navigation attempt.

package/dist/svelte/export/svelte/index.js

@@ -0,0 +1,6 @@
+export { createIntor } from '../../src/client/svelte/runtime/create-intor.js';
+import 'svelte/store';
+import '../../src/core/error/intor-error.js';
+import 'logry';
+import 'keyv';
+export { getClientLocale } from '../../src/client/helpers/get-client-locale.js';

package/dist/svelte/src/client/helpers/get-client-locale.js

@@ -0,0 +1,27 @@
+import '../../core/error/intor-error.js';
+import { normalizeLocale } from '../../core/utils/normalizers/normalize-locale.js';
+import 'logry';
+import 'keyv';
+import { detectBrowserLocale } from '../shared/utils/locale/detect-browser-locale.js';
+import { getLocaleCookieBrowser } from '../shared/utils/locale/get-locale-cookie-browser.js';
+
+/**
+ * Resolve the locale in a client-only environment.
+ *
+ * This helper is intended for pure CSR setups (e.g. Vite).
+ *
+ * For framework-based apps, prefer `useTranslator()`.
+ *
+ * - Client-side only
+ */
+function getClientLocale(config) {
+    const { defaultLocale, supportedLocales, cookie } = config;
+    // Locale from browser cookie
+    const cookieLocale = getLocaleCookieBrowser(cookie.name);
+    // Locale from browser preference
+    const browserLocale = detectBrowserLocale();
+    const localeCandidate = cookieLocale || browserLocale;
+    return normalizeLocale(localeCandidate, supportedLocales) || defaultLocale;
+}
+
+export { getClientLocale };

package/dist/svelte/src/client/shared/messages/create-refetch-messages.js

@@ -0,0 +1,61 @@
+import '../../../core/error/intor-error.js';
+import { deepMerge } from '../../../core/utils/deep-merge.js';
+import { resolveLoaderOptions } from '../../../core/utils/resolve-loader-options.js';
+import 'logry';
+import { loadRemoteMessages } from '../../../core/messages/load-remote-messages/load-remote-messages.js';
+import 'keyv';
+
+/**
+ * Creates a framework-agnostic message refetcher.
+ *
+ * - At most one remote request is active at any time
+ * - Previous in-flight requests are aborted on subsequent calls
+ * - State updates are applied only for the latest, non-aborted request
+ */
+const createRefetchMessages = ({ config, onLoadingStart, onLoadingEnd, onMessages, }) => {
+    // Tracks the currently active remote request for this refetcher instance
+    let controller = null;
+    return async function refetchMessages(newLocale) {
+        // No-op when remote loading is not enabled
+        const loader = resolveLoaderOptions(config);
+        if (!loader || loader.type !== "remote")
+            return;
+        // Abort previous request
+        controller?.abort();
+        const currentController = new AbortController();
+        controller = currentController;
+        onLoadingStart?.();
+        try {
+            const loadedMessages = await loadRemoteMessages({
+                // --- Messages Scope ---
+                locale: newLocale,
+                fallbackLocales: config.fallbackLocales[newLocale] || [],
+                namespaces: loader.namespaces,
+                rootDir: loader.rootDir,
+                // --- Remote Source ---
+                url: loader.url,
+                headers: loader.headers,
+                signal: currentController.signal,
+                // --- Caching ---
+                cacheOptions: config.cache,
+                // --- Observability ---
+                loggerOptions: config.logger,
+            });
+            // Apply state updates only when this request is still the active one
+            // and has not been aborted.
+            if (controller === currentController &&
+                !currentController.signal.aborted) {
+                onMessages?.(deepMerge(config.messages, loadedMessages));
+            }
+        }
+        finally {
+            // Clear loading state only if this request is still the active one
+            if (controller === currentController &&
+                !currentController.signal.aborted) {
+                onLoadingEnd?.();
+            }
+        }
+    };
+};
+
+export { createRefetchMessages };

package/dist/svelte/src/client/shared/utils/locale/detect-browser-locale.js

@@ -0,0 +1,12 @@
+/**
+ * Detect the preferred locale from the browser.
+ *
+ * - Client-side only
+ */
+function detectBrowserLocale() {
+    if (typeof navigator === "undefined")
+        return undefined;
+    return navigator.languages?.[0] || navigator.language || undefined;
+}
+
+export { detectBrowserLocale };

package/dist/svelte/src/client/shared/utils/locale/get-locale-cookie-browser.js

@@ -0,0 +1,16 @@
+/**
+ * Gets the locale value from the browser cookie.
+ *
+ * - Client-side only
+ */
+function getLocaleCookieBrowser(cookieName) {
+    if (typeof document === "undefined")
+        return undefined;
+    const cookies = document.cookie.split(";").map((c) => c.trim());
+    const entry = cookies.find((c) => c.startsWith(`${cookieName}=`));
+    if (!entry)
+        return undefined;
+    return decodeURIComponent(entry.slice(cookieName.length + 1));
+}
+
+export { getLocaleCookieBrowser };

package/dist/svelte/src/client/shared/utils/locale/set-document-locale.js

@@ -0,0 +1,12 @@
+/**
+ * Sets the document language attribute.
+ *
+ * - Client-side only
+ */
+function setDocumentLocale(locale) {
+    if (typeof document === "undefined")
+        return;
+    document.documentElement.lang = locale;
+}
+
+export { setDocumentLocale };

package/dist/svelte/src/client/svelte/runtime/create-intor.js

@@ -0,0 +1,70 @@
+import { Translator } from 'intor-translator';
+import { writable, readable, derived, get } from 'svelte/store';
+import { attachLocaleEffects } from './effects/locale-effects.js';
+import { attachMessagesEffects } from './effects/messages-effects.js';
+
+function createIntor({ config, initialLocale, initialMessages, handlers, plugins, onLocaleChange, isLoading: externalIsLoading, }) {
+    // ---------------------------------------------------------------------------
+    // Internal state
+    // ---------------------------------------------------------------------------
+    const locale = writable(initialLocale);
+    const runtimeMessages = writable(null);
+    const internalIsLoading = writable(false);
+    // -----------------------------------------------------------------------------
+    // Locale transition
+    // -----------------------------------------------------------------------------
+    /** Request a locale change. */
+    async function setLocale(next) {
+        const current = get(locale);
+        if (next === current)
+            return;
+        locale.set(next);
+        onLocaleChange?.(next); // Notify external listener (fire-and-forget)
+    }
+    // ---------------------------------------------------------------------------
+    // Effective state
+    // ---------------------------------------------------------------------------
+    const externalIsLoadingStore = externalIsLoading ?? readable(false);
+    // external > internal
+    const effectiveIsLoading = derived([externalIsLoadingStore, internalIsLoading], ([$external, $internal]) => $external || $internal);
+    // runtime (client refetch) > initial > config (static)
+    const effectiveMessages = derived([runtimeMessages, initialMessages ?? readable(undefined)], ([$runtime, $initial]) => $runtime || $initial || config.messages || {});
+    // ---------------------------------------------------------------------------
+    // Translator
+    // ---------------------------------------------------------------------------
+    const translator = derived([effectiveMessages, locale, effectiveIsLoading], ([$messages, $locale, $isLoading]) => new Translator({
+        messages: $messages,
+        locale: $locale,
+        isLoading: $isLoading,
+        fallbackLocales: config.fallbackLocales,
+        loadingMessage: config.translator?.loadingMessage,
+        missingMessage: config.translator?.missingMessage,
+        handlers,
+        plugins,
+    }));
+    // ---------------------------------------------------------------------------
+    // Side effects
+    // ---------------------------------------------------------------------------
+    const detachLocaleEffects = attachLocaleEffects(locale, config);
+    const detachMessagesEffects = attachMessagesEffects({
+        config,
+        locale,
+        runtimeMessages,
+        internalIsLoading,
+    });
+    return {
+        config,
+        locale,
+        setLocale,
+        messages: effectiveMessages,
+        isLoading: effectiveIsLoading,
+        translator,
+        // optional cleanup
+        destroy() {
+            detachLocaleEffects();
+            detachMessagesEffects();
+        },
+    };
+}
+
+export { createIntor };

package/dist/svelte/src/client/svelte/runtime/effects/locale-effects.js

@@ -0,0 +1,19 @@
+import { setLocaleCookieBrowser } from '../../../shared/utils/locale/set-locale-cookie-browser.js';
+import { setDocumentLocale } from '../../../shared/utils/locale/set-document-locale.js';
+
+/**
+ * Attach locale-related browser side effects.
+ *
+ * - Sync locale cookie
+ * - Sync <html lang="">
+ *
+ * Returns an unsubscribe function.
+ */
+function attachLocaleEffects(locale, config) {
+    return locale.subscribe((value) => {
+        setLocaleCookieBrowser(config.cookie, value);
+        setDocumentLocale(value);
+    });
+}
+
+export { attachLocaleEffects };

package/dist/svelte/src/client/svelte/runtime/effects/messages-effects.js

@@ -0,0 +1,23 @@
+import { createRefetchMessages } from '../../../shared/messages/create-refetch-messages.js';
+
+function attachMessagesEffects({ locale, config, runtimeMessages, internalIsLoading, }) {
+    // Prepares message refetch function.
+    const refetchMessages = createRefetchMessages({
+        config,
+        onLoadingStart: () => internalIsLoading.set(true),
+        onLoadingEnd: () => internalIsLoading.set(false),
+        onMessages: (messages) => runtimeMessages.set(messages),
+    });
+    // Refetch messages when locale changes (except initial render).
+    let isInitial = true;
+    const unsubscribe = locale.subscribe((value) => {
+        if (isInitial) {
+            isInitial = false;
+            return;
+        }
+        refetchMessages(value);
+    });
+    return unsubscribe;
+}
+
+export { attachMessagesEffects };

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

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

package/dist/svelte/src/core/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/svelte/src/core/logger/global-logger-pool.js

@@ -0,0 +1,8 @@
+function getGlobalLoggerPool() {
+    if (!globalThis.__INTOR_LOGGER_POOL__) {
+        globalThis.__INTOR_LOGGER_POOL__ = new Map();
+    }
+    return globalThis.__INTOR_LOGGER_POOL__;
+}
+
+export { getGlobalLoggerPool };

package/dist/svelte/src/core/messages/load-remote-messages/fetch-locale-messages/fetch-locale-messages.js

@@ -0,0 +1,55 @@
+import { getLogger } from '../../../logger/get-logger.js';
+import { isValidMessages } from '../../utils/is-valid-messages.js';
+import { buildSearchParams } from './utils/build-search-params.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 ({ locale, namespaces, rootDir, url: rawUrl, headers: rawHeaders, signal, extraOptions: { loggerOptions }, }) => {
+    const baseLogger = getLogger(loggerOptions);
+    const logger = baseLogger.child({ scope: "fetch-locale-messages" });
+    const searchParams = buildSearchParams({ locale, rootDir, namespaces });
+    const url = `${rawUrl}?${searchParams.toString()}`;
+    try {
+        // Headers
+        const headers = {
+            "Content-Type": "application/json",
+            ...rawHeaders,
+        };
+        // Fetch
+        const response = await fetch(url, {
+            method: "GET",
+            headers: 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, url });
+            return;
+        }
+        logger.warn("Fetching locale messages failed.", {
+            locale,
+            url,
+            searchParams: decodeURIComponent(searchParams.toString()),
+            error,
+        });
+        return;
+    }
+};
+
+export { fetchLocaleMessages };

package/dist/svelte/src/core/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/svelte/src/core/messages/load-remote-messages/load-remote-messages.js

@@ -0,0 +1,108 @@
+import { getLogger } from '../../logger/get-logger.js';
+import { normalizeCacheKey } from '../../utils/normalizers/normalize-cache-key.js';
+import { fetchLocaleMessages } from './fetch-locale-messages/fetch-locale-messages.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 ({ locale, fallbackLocales, namespaces, rootDir, url, headers, signal, pool, cacheOptions, allowCacheWrite = false, loggerOptions, }) => {
+    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.", { url });
+    // --- 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({
+                locale: candidateLocale,
+                namespaces,
+                rootDir,
+                url,
+                headers,
+                signal,
+                extraOptions: { loggerOptions },
+            });
+            // 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/svelte/src/core/messages/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 };