intor 2.3.5 → 2.3.7

package/dist/vue/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/vue/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 };

package/dist/vue/src/core/utils/deep-merge.js

@@ -0,0 +1,31 @@
+/**
+ * Deeply merges two objects.
+ *
+ * - Nested objects → merged recursively
+ * - Array / primitive → b overwrites a
+ *
+ * This function always returns a plain object.
+ */
+const deepMerge = (a = {}, b = {}) => {
+    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)) {
+                result[key] = deepMerge(av, bv);
+            }
+            else {
+                result[key] = bv;
+            }
+        }
+    }
+    return result;
+};
+
+export { deepMerge };

package/dist/vue/src/core/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/vue/src/core/utils/normalizers/normalize-locale.js

@@ -0,0 +1,59 @@
+const toCanonical = (input) => {
+    try {
+        return Intl.getCanonicalLocales(input)[0];
+    }
+    catch {
+        return;
+    }
+};
+/**
+ * Normalizes a locale string and resolves the best match
+ * from a list of supported locales.
+ *
+ * Resolution strategy:
+ *
+ * 1. Exact canonical match (BCP 47)
+ * 2. Base language fallback
+ *    - Falls back by base language when no exact match is found
+ *      (e.g. `"en"` → `"en-US"`).
+ *    - Script and region subtags are ignored during this step
+ *      (e.g. `"zh-Hans"` → `"zh-Hant-TW"`)
+ *    - Preference is determined by the order of `supportedLocales`.
+ *
+ * Returns `undefined` if no suitable match is found.
+ *
+ * Notes:
+ * - Invalid locale inputs are ignored gracefully.
+ * - Always returns an original entry from `supportedLocales`.
+ * - Requires `Intl` locale support in the runtime.
+ */
+const normalizeLocale = (locale, supportedLocales = []) => {
+    if (!locale || supportedLocales.length === 0)
+        return;
+    const canonicalLocale = toCanonical(locale);
+    if (!canonicalLocale)
+        return;
+    const supportedCanonicalMap = new Map();
+    for (const l of supportedLocales) {
+        const normalized = toCanonical(l);
+        if (normalized) {
+            supportedCanonicalMap.set(normalized, l);
+        }
+    }
+    // 1. Exact match
+    if (supportedCanonicalMap.has(canonicalLocale)) {
+        return supportedCanonicalMap.get(canonicalLocale);
+    }
+    const baseLang = canonicalLocale.split("-")[0];
+    // 2. Match by same base language (e.g., "en" matches "en-US" or "en-GB")
+    for (const [key, original] of supportedCanonicalMap) {
+        const supportedBase = key.split("-")[0];
+        if (supportedBase === baseLang) {
+            return original;
+        }
+    }
+    // 3. No match
+    return;
+};
+
+export { normalizeLocale };

package/dist/vue/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "intor",
-  "version": "2.3.5",
+  "version": "2.3.7",
   "description": "A modular and extensible i18n core designed for TypeScript and JavaScript projects. Intor enables custom translation logic with support for both frontend and backend environments, featuring runtime configuration, caching, adapters, and message loaders.",
   "author": "Yiming Liao",
   "homepage": "https://github.com/yiming-liao/intor#readme",
@@ -64,6 +64,14 @@
     "./next/server": {
       "import": "./dist/next/export/next/server/index.js",
       "types": "./dist/types/export/next/server/index.d.ts"
+    },
+    "./vue": {
+      "import": "./dist/vue/export/vue/index.js",
+      "types": "./dist/types/export/vue/index.d.ts"
+    },
+    "./svelte": {
+      "import": "./dist/svelte/export/svelte/index.js",
+      "types": "./dist/types/export/svelte/index.d.ts"
     }
   },
   "main": "./dist/export/index.js",
@@ -89,15 +97,15 @@
     "examples:html": "vite --config examples/html/vite.config.ts"
   },
   "dependencies": {
-    "intor-translator": "1.3.1",
+    "intor-translator": "1.3.2",
     "keyv": "5.5.5",
     "logry": "2.1.5",
     "p-limit": "7.2.0"
   },
   "devDependencies": {
-    "@rollup/plugin-alias": "^6.0.0",
+    "@rollup/plugin-alias": "6.0.0",
     "@rollup/plugin-typescript": "12.3.0",
-    "@rollup/pluginutils": "^5.3.0",
+    "@rollup/pluginutils": "5.3.0",
     "@testing-library/dom": "10.4.1",
     "@testing-library/jest-dom": "6.9.1",
     "@testing-library/react": "16.3.1",
@@ -118,7 +126,7 @@
     "eslint-plugin-unused-imports": "4.1.4",
     "jsdom": "27.3.0",
     "knip": "5.69.1",
-    "magic-string": "^0.30.21",
+    "magic-string": "0.30.21",
     "next": "16.0.3",
     "prettier": "3.6.2",
     "react": "19.0.0",
@@ -126,12 +134,14 @@
     "remark": "15.0.1",
     "remark-gfm": "4.0.1",
     "rollup": "4.53.3",
+    "svelte": "5.46.1",
     "tsc-alias": "1.8.16",
     "tsd": "0.33.0",
     "typescript": "5.8.3",
     "typescript-eslint": "8.32.1",
     "vite": "7.3.0",
     "vite-tsconfig-paths": "6.0.3",
-    "vitest": "4.0.16"
+    "vitest": "4.0.16",
+    "vue": "3.5.26"
   }
 }

package/dist/next/src/client/react/contexts/config/context.js

@@ -1,3 +0,0 @@
-import * as React from 'react';
-
-React.createContext(undefined);

package/dist/next/src/client/react/contexts/locale/context.js

@@ -1,3 +0,0 @@
-import * as React from 'react';
-
-React.createContext(undefined);

package/dist/next/src/client/react/contexts/messages/context.js

@@ -1,3 +0,0 @@
-import * as React from 'react';
-
-React.createContext(undefined);

package/dist/next/src/client/react/contexts/translator/context.js

@@ -1,3 +0,0 @@
-import * as React from 'react';
-
-React.createContext(undefined);

package/dist/next/src/client/react/contexts/translator-runtime/context.js

@@ -1,3 +0,0 @@
-import * as React from 'react';
-
-React.createContext(undefined);

package/dist/next/src/config/constants/cache.constants.js

@@ -1,7 +0,0 @@
-// Default cache options
-const DEFAULT_CACHE_OPTIONS = {
-    enabled: process.env.NODE_ENV === "production",
-    ttl: 60 * 60 * 1000, // 1 hour
-};
-
-export { DEFAULT_CACHE_OPTIONS };

package/dist/react/src/client/react/contexts/config/context.js

@@ -1,5 +0,0 @@
-import * as React from 'react';
-
-const ConfigContext = React.createContext(undefined);
-
-export { ConfigContext };

package/dist/react/src/client/react/contexts/config/hook.js

@@ -1,11 +0,0 @@
-import * as React from 'react';
-import { ConfigContext } from './context.js';
-
-function useConfig() {
-    const context = React.useContext(ConfigContext);
-    if (!context)
-        throw new Error("useConfig must be used within ConfigProvider");
-    return context;
-}
-
-export { useConfig };

package/dist/react/src/client/react/contexts/config/provider.js

@@ -1,14 +0,0 @@
-"use client";
-import { jsx } from 'react/jsx-runtime';
-import * as React from 'react';
-import { ConfigContext } from './context.js';
-
-function ConfigProvider({ value: { config }, children, }) {
-    // context value
-    const value = React.useMemo(() => ({
-        config,
-    }), [config]);
-    return (jsx(ConfigContext.Provider, { value: value, children: children }));
-}
-
-export { ConfigProvider };

package/dist/react/src/client/react/contexts/intor-provider/intor-provider.js

@@ -1,17 +0,0 @@
-"use client";
-import { jsx } from 'react/jsx-runtime';
-import { ConfigProvider } from '../config/provider.js';
-import 'react';
-import '../config/context.js';
-import { LocaleProvider } from '../locale/provider.js';
-import '../locale/context.js';
-import { MessagesProvider } from '../messages/provider.js';
-import '../messages/context.js';
-import { TranslatorProvider } from '../translator/provider.js';
-import '../translator/context.js';
-
-const IntorProvider = ({ value: { config, initialLocale, messages = config.messages, onLocaleChange, isLoading, }, children, }) => {
-    return (jsx(ConfigProvider, { value: { config }, children: jsx(LocaleProvider, { value: { initialLocale, onLocaleChange }, children: jsx(MessagesProvider, { value: { messages }, children: jsx(TranslatorProvider, { value: { isLoading }, children: children }) }) }) }));
-};
-
-export { IntorProvider };

package/dist/react/src/client/react/contexts/locale/context.js

@@ -1,5 +0,0 @@
-import * as React from 'react';
-
-const LocaleContext = React.createContext(undefined);
-
-export { LocaleContext };

package/dist/react/src/client/react/contexts/locale/hook.js

@@ -1,11 +0,0 @@
-import * as React from 'react';
-import { LocaleContext } from './context.js';
-
-function useLocale() {
-    const context = React.useContext(LocaleContext);
-    if (!context)
-        throw new Error("useLocale must be used within a LocaleProvider");
-    return context;
-}
-
-export { useLocale };

package/dist/react/src/client/react/contexts/locale/provider.js

@@ -1,38 +0,0 @@
-"use client";
-import { jsx } from 'react/jsx-runtime';
-import * as React from 'react';
-import '../config/context.js';
-import { useConfig } from '../config/hook.js';
-import { setLocaleCookieBrowser } from '../../../shared/utils/locale/set-locale-cookie-browser.js';
-import { setDocumentLocale } from '../../../shared/utils/locale/set-document-locale.js';
-import { LocaleContext } from './context.js';
-import { changeLocale } from './utils/change-locale.js';
-
-function LocaleProvider({ value: { initialLocale, onLocaleChange }, children, }) {
-    const { config } = useConfig();
-    const [locale, setLocaleState] = React.useState(initialLocale);
-    // Request a locale change.
-    const setLocale = React.useCallback(async (newLocale) => {
-        changeLocale({
-            locale,
-            newLocale,
-            fullReloadRequired: config.loader?.type === "local",
-            setLocaleState,
-        });
-        // Notify external listener (fire-and-forget)
-        onLocaleChange?.(newLocale);
-    }, [locale, config.loader, onLocaleChange]);
-    // Sync locale-related browser side effects.
-    React.useEffect(() => {
-        setLocaleCookieBrowser(config.cookie, locale);
-        setDocumentLocale(locale);
-    }, [config.cookie, locale]);
-    // context value
-    const value = React.useMemo(() => ({
-        locale,
-        setLocale,
-    }), [locale, setLocale]);
-    return (jsx(LocaleContext.Provider, { value: value, children: children }));
-}
-
-export { LocaleProvider };

package/dist/react/src/client/react/contexts/locale/utils/change-locale.js

@@ -1,26 +0,0 @@
-/**
- * Requests a locale change on the client.
- *
- * - This function updates the locale state only.
- * - Side effects such as cookie persistence, `<html lang>` updates,
- * or message refetching are handled by higher-level providers.
- *
- * Notes:
- * - When using a `local` loader, client-side locale switching
- *   requires a full page reload to load new message bundles.
- */
-const changeLocale = ({ locale, newLocale, fullReloadRequired, setLocaleState, }) => {
-    // No-op when locale does not change
-    if (newLocale === locale)
-        return;
-    // Informational warning when a full reload is required
-    if (fullReloadRequired) {
-        console.warn(`[Intor] Locale change requested while using a "local" loader. ` +
-            `Client-side navigation alone will not load new messages. ` +
-            `Use the provided <Link> wrapper or trigger a full page reload.`);
-    }
-    // Update locale state
-    setLocaleState(newLocale);
-};
-
-export { changeLocale };

package/dist/react/src/client/react/contexts/messages/context.js

@@ -1,5 +0,0 @@
-import * as React from 'react';
-
-const MessagesContext = React.createContext(undefined);
-
-export { MessagesContext };

package/dist/react/src/client/react/contexts/messages/hook.js

@@ -1,11 +0,0 @@
-import * as React from 'react';
-import { MessagesContext } from './context.js';
-
-function useMessages() {
-    const context = React.useContext(MessagesContext);
-    if (!context)
-        throw new Error("useMessages must be used within a MessagesProvider");
-    return context;
-}
-
-export { useMessages };

package/dist/react/src/client/react/contexts/messages/provider.js

@@ -1,39 +0,0 @@
-"use client";
-import { jsx } from 'react/jsx-runtime';
-import * as React from 'react';
-import '../config/context.js';
-import { useConfig } from '../config/hook.js';
-import '../locale/context.js';
-import { useLocale } from '../locale/hook.js';
-import { useRefetchMessages } from './utils/use-refetch-messages.js';
-import { MessagesContext } from './context.js';
-
-function MessagesProvider({ value: { messages = {} }, children, }) {
-    const { config } = useConfig();
-    const { locale } = useLocale();
-    const [runtimeMessages, setRuntimeMessages] = React.useState(null);
-    const [isLoadingMessages, setIsLoadingMessages] = React.useState(false);
-    const isInitialRenderRef = React.useRef(true);
-    // Prepares message refetch function.
-    const { refetchMessages } = useRefetchMessages({
-        config,
-        setRuntimeMessages,
-        setIsLoadingMessages,
-    });
-    // Refetch messages when locale changes (except initial render).
-    React.useEffect(() => {
-        if (isInitialRenderRef.current) {
-            isInitialRenderRef.current = false;
-            return;
-        }
-        refetchMessages(locale);
-    }, [refetchMessages, locale]);
-    // context value
-    const value = React.useMemo(() => ({
-        messages: runtimeMessages || messages,
-        isLoading: isLoadingMessages,
-    }), [runtimeMessages, messages, isLoadingMessages]);
-    return (jsx(MessagesContext.Provider, { value: value, children: children }));
-}
-
-export { MessagesProvider };