intor 2.3.8 → 2.3.10

package/README.md

@@ -15,88 +15,3 @@ Fast to start, easy to extend, and free from the usual i18n heaviness.
 [![License](https://img.shields.io/npm/l/intor?style=flat&colorA=000000&colorB=000000)](LICENSE)
 
 </div>
-
-<div align="center">
-
-#### 🍳 Cooking the Intor v2 docs, crafting them to perfection...
-
-</div>
-
----
-
-Intor separates language translation from semantic rendering.  
-ICU operates at the text-translation layer, while semantic tags  
-are parsed and rendered in a dedicated AST-based rendering phase.
-
-```
-┌──────────────────────────────────────────────┐
-│                Application                   │
-│                                              │
-│  t() / tRich() / <T />                       │
-└───────────────────────────┬──────────────────┘
-                            │
-                            ▼
-┌──────────────────────────────────────────────┐
-│        Translator (Language / Semantic)      │
-│              intor-translator                │
-│                                              │
-│  Responsibilities:                           │
-│  - Resolve message key                       │
-│  - Locale resolution & fallback              │
-│  - Message loading                           │
-│  - Text-level interpolation                  │
-│    • {name}, {count}                         │
-│    • plural / select                         │
-│    • ICU MessageFormat (optional)            │
-│      (ignoreTag: true)                       │
-│                                              │
-│  Output:                                     │
-│  - Translated string                         │
-│  - May still contain <semantic tags>         │
-└───────────────────────────┬──────────────────┘
-                            │
-                            ▼
-┌──────────────────────────────────────────────┐
-│      Semantic Parsing & AST Construction     │
-│                                              │
-│  Responsibilities:                           │
-│  - Tokenize semantic tags                    │
-│    • <b>, <link>, <Component>                │
-│  - Build semantic AST                        │
-│    • TextNode                                │
-│    • TagNode                                 │
-│                                              │
-│  Note:                                       │
-│  - Independent from ICU / formatter          │
-│  - Pure semantic structure                   │
-└───────────────────────────┬──────────────────┘
-                            │
-                            ▼
-┌──────────────────────────────────────────────┐
-│        Semantic Rendering (Renderer)         │
-│                                              │
-│  Responsibilities:                           │
-│  - Traverse semantic AST                     │
-│  - Render TextNode                           │
-│  - Render TagNode                            │
-│                                              │
-│  Renderer decides output type:               │
-│  - string                                    │
-│  - ReactNode                                 │
-│  - Vue / Svelte nodes                        │
-│  - Markdown / CLI output                     │
-│                                              │
-│  Optional extensions:                        │
-│  - Custom tag renderers                      │
-│  - Rich components                           │
-└───────────────────────────┬──────────────────┘
-                            │
-                            ▼
-┌──────────────────────────────────────────────┐
-│                 Final Output                 │
-│                                              │
-│  - Rendered rich content                     │
-│  - Framework-specific result                 │
-│                                              │
-└──────────────────────────────────────────────┘
-```

package/dist/core/export/index.js

@@ -1,9 +1,14 @@
 export { PREFIX_PLACEHOLDER } from '../src/core/constants/prefix-placeholder.js';
 export { IntorError, IntorErrorCode } from '../src/core/error/intor-error.js';
 export { deepMerge } from '../src/core/utils/deep-merge.js';
-export { localizePathname } from '../src/core/utils/pathname/localize-pathname.js';
+export { resolveLoaderOptions } from '../src/core/utils/resolve-loader-options.js';
 import 'logry';
 export { clearLoggerPool } from '../src/core/logger/global-logger-pool.js';
 export { isValidMessages } from '../src/core/messages/utils/is-valid-messages.js';
 export { clearMessagesPool, setGlobalMessagesPool } from '../src/core/messages/global-messages-pool.js';
-import 'intor-translator';
+export { mergeMessages } from '../src/core/messages/merge-messages.js';
+export { defineIntorConfig } from '../src/config/define-intor-config.js';
+import '../src/config/constants/cookie.js';
+import '../src/config/constants/cache.js';
+export { localizePathname } from '../src/routing/pathname/localize-pathname.js';
+export { Translator } from 'intor-translator';

package/dist/core/export/server/index.js

@@ -1,4 +1,6 @@
 export { intor } from '../../src/server/intor/intor.js';
 export { loadMessages } from '../../src/server/messages/load-messages.js';
-export { getTranslator } from '../../src/server/translator/get-translator.js';
+import 'intor-translator';
+import 'logry';
+export { getTranslator } from '../../src/server/helpers/get-translator.js';
 export { loadMessagesFromUrl } from '../../src/server/helpers/local-messages-from-url.js';

package/dist/core/src/config/constants/cookie.js

@@ -3,7 +3,7 @@ const DEFAULT_COOKIE_OPTIONS = {
     enabled: true,
     persist: true,
     name: "intor.locale",
-    domain: null,
+    domain: undefined,
     path: "/",
     maxAge: 60 * 60 * 24 * 365, // 365 days
     httpOnly: false,

package/dist/core/src/config/constants/routing.js

@@ -2,9 +2,14 @@
 const DEFAULT_ROUTING_OPTIONS = {
     locale: {
         sources: ["path", "query", "cookie", "detected"],
-        queryKey: "locale",
+        query: { key: "locale" },
+    },
+    navigation: {
+        carrier: "path",
+        path: { prefix: "none" },
+        query: { key: "locale" },
+        host: { map: {} },
     },
-    prefix: "none",
     firstVisit: {
         localeSource: "browser",
         redirect: true,

package/dist/core/src/config/resolvers/resolve-routing-options.js

@@ -13,6 +13,26 @@ const resolveRoutingOptions = (routing = {}) => {
         locale: {
             ...DEFAULT_ROUTING_OPTIONS.locale,
             ...routing.locale,
+            query: {
+                ...DEFAULT_ROUTING_OPTIONS.locale.query,
+                ...routing.locale?.query,
+            },
+        },
+        navigation: {
+            ...DEFAULT_ROUTING_OPTIONS.navigation,
+            ...routing.navigation,
+            path: {
+                ...DEFAULT_ROUTING_OPTIONS.navigation.path,
+                ...routing.navigation?.path,
+            },
+            query: {
+                ...DEFAULT_ROUTING_OPTIONS.navigation.query,
+                ...routing.navigation?.query,
+            },
+            host: {
+                ...DEFAULT_ROUTING_OPTIONS.navigation.host,
+                ...routing.navigation?.host,
+            },
         },
         firstVisit: {
             ...DEFAULT_ROUTING_OPTIONS.firstVisit,

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

@@ -12,10 +12,12 @@ class IntorError extends Error {
 }
 var IntorErrorCode;
 (function (IntorErrorCode) {
-    // intor-config
+    // 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";
+    // runtime
+    IntorErrorCode["RUNTIME_NOT_INITIALIZED"] = "INTOR_RUNTIME_NOT_INITIALIZED";
 })(IntorErrorCode || (IntorErrorCode = {}));
 
 export { IntorError, IntorErrorCode };

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

@@ -5,16 +5,16 @@ import { fetchLocaleMessages } from './fetch-locale-messages/fetch-locale-messag
 /**
  * Load locale messages from a remote API.
  *
- * This function acts as the orchestration layer for remote message loading.
- * It is responsible for:
+ * This function serves as the orchestration layer for remote message loading.
+ * It coordinates:
  *
- * - Resolving fallback locales in order
- * - Coordinating cache read / write behavior
+ * - Locale resolution with fallbacks
+ * - 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 loadRemoteMessages = async ({ id, 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
@@ -24,16 +24,20 @@ const loadRemoteMessages = async ({ locale, fallbackLocales, namespaces, rootDir
     }
     const start = performance.now();
     logger.debug("Loading remote messages.", { url });
-    // --- Cache key ---
+    // ---------------------------------------------------------------------------
+    // Cache key resolution
+    // ---------------------------------------------------------------------------
     const cacheKey = normalizeCacheKey([
-        loggerOptions.id,
+        id,
         "loaderType:remote",
         rootDir,
         locale,
-        (fallbackLocales ?? []).toSorted().join(","),
-        (namespaces ?? []).toSorted().join(","),
+        (fallbackLocales || []).toSorted().join(","),
+        (namespaces || []).toSorted().join(","),
     ]);
-    // --- Cache read ---
+    // ---------------------------------------------------------------------------
+    // Cache read
+    // ---------------------------------------------------------------------------
     if (cacheOptions.enabled && cacheKey) {
         const cached = await pool?.get(cacheKey);
         if (signal?.aborted) {
@@ -45,9 +49,11 @@ const loadRemoteMessages = async ({ locale, fallbackLocales, namespaces, rootDir
             return cached;
         }
     }
+    // ---------------------------------------------------------------------------
+    // Resolve locale messages with ordered fallback strategy
+    // ---------------------------------------------------------------------------
     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;
@@ -87,13 +93,17 @@ const loadRemoteMessages = async ({ locale, fallbackLocales, namespaces, rootDir
             });
         }
     }
-    // --- Cache write ---
-    if (cacheOptions.enabled && allowCacheWrite && cacheKey && messages) {
+    // ---------------------------------------------------------------------------
+    // Cache write (explicitly permitted)
+    // ---------------------------------------------------------------------------
+    if (cacheOptions.enabled && allowCacheWrite) {
         if (signal?.aborted) {
             logger.debug("Remote message loading aborted before cache write.");
             return;
         }
-        await pool?.set(cacheKey, messages, cacheOptions.ttl);
+        if (cacheKey && messages) {
+            await pool?.set(cacheKey, messages, cacheOptions.ttl);
+        }
     }
     // Final success log with resolved locale and timing
     if (messages) {

package/dist/core/src/core/messages/merge-messages.js

@@ -0,0 +1,33 @@
+import { getLogger } from '../logger/get-logger.js';
+import { deepMerge } from '../utils/deep-merge.js';
+
+/**
+ * Merge locale-specific messages with runtime overrides.
+ *
+ * - Only merges messages under the given locale
+ * - Emits debug logs for add / override events
+ */
+function mergeMessages(a, b, { config, locale, onEvent }) {
+    const baseLogger = getLogger({ ...config.logger, id: config.id });
+    const logger = baseLogger.child({ scope: "merge-messages" });
+    // Merge messages for the active locale only
+    const merged = deepMerge(a?.[locale] ?? {}, b?.[locale] ?? {}, {
+        onOverride: (event) => {
+            if (onEvent) {
+                onEvent(event);
+                return;
+            }
+            const { kind, path, next, prev } = event;
+            if (kind === "add")
+                return;
+            logger.debug(`Override | ${locale}: "${path}"`, { prev, next });
+        },
+    });
+    // Preserve other locales, update only the target one
+    return {
+        ...a,
+        [locale]: merged,
+    };
+}
+
+export { mergeMessages };

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

@@ -1,28 +1,44 @@
 /**
- * Deeply merges two objects.
+ * Deeply merges two plain objects.
  *
- * - Nested objects → merged recursively
- * - Array / primitive → b overwrites a
+ * - Nested plain objects → merged recursively
+ * - Arrays / primitives → `b` overwrites `a`
  *
- * This function always returns a plain object.
+ * Debug behavior (optional):
+ * - Emits override events via `onOverride`
+ * - Zero overhead when no options are provided
+ *
+ * This function always returns a new plain object.
  */
-const deepMerge = (a = {}, b = {}) => {
+const deepMerge = (a = {}, b = {}, options) => {
     const result = { ...a };
+    const basePath = options?._path ?? [];
+    // Iterate only over b's own enumerable properties
     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;
-            }
+        if (!Object.prototype.hasOwnProperty.call(b, key))
+            continue;
+        const aValue = a[key];
+        const bValue = b[key];
+        const nextPath = [...basePath, key];
+        // Recursively merge when both sides are plain objects
+        if (aValue &&
+            bValue &&
+            typeof aValue === "object" &&
+            typeof bValue === "object" &&
+            !Array.isArray(aValue) &&
+            !Array.isArray(bValue)) {
+            result[key] = deepMerge(aValue, bValue, options ? { ...options, _path: nextPath } : undefined);
+        }
+        else {
+            // Emit override event only when debugging is enabled
+            const isAdd = aValue === undefined;
+            options?.onOverride?.({
+                path: nextPath.join("."),
+                prev: aValue,
+                next: bValue,
+                kind: isAdd ? "add" : "override",
+            });
+            result[key] = bValue;
         }
     }
     return result;

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

@@ -18,6 +18,15 @@
  *   for the given runtime.
  */
 const resolveLoaderOptions = (config, runtime) => {
+    // --- runtime: client ---
+    if (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;
+    }
     // --- runtime: server ---
     return config.server?.loader ?? config.loader;
 };

package/dist/core/src/{core/utils → routing}/pathname/get-unprefixed-pathname.js

@@ -1,4 +1,7 @@
-import { normalizePathname } from '../normalizers/normalize-pathname.js';
+import '../../core/error/intor-error.js';
+import { normalizePathname } from '../../core/utils/normalizers/normalize-pathname.js';
+import 'logry';
+import 'keyv';
 
 /**
  * Returns a canonical, locale-agnostic pathname.

package/dist/{react/src/core/utils → core/src/routing}/pathname/locale-prefix-pathname.js

@@ -1,5 +1,8 @@
-import { PREFIX_PLACEHOLDER } from '../../constants/prefix-placeholder.js';
-import { normalizePathname } from '../normalizers/normalize-pathname.js';
+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 'keyv';
 
 /**
  * Applies routing prefix strategy by resolving the locale placeholder.
@@ -16,8 +19,7 @@ import { normalizePathname } from '../normalizers/normalize-pathname.js';
  * ```
  */
 const localePrefixPathname = (config, standardizedPathname, locale) => {
-    const { routing } = config;
-    const { prefix } = routing;
+    const { prefix } = config.routing.navigation.path;
     if (prefix !== "none" && !locale) {
         throw new Error('No locale when using prefix "all", "except-default"');
     }

package/dist/{react/src/core/utils → core/src/routing}/pathname/localize-pathname.js

@@ -25,11 +25,11 @@ const localizePathname = (config, rawPathname, locale) => {
     // 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);
+    const pathname = localePrefixPathname(config, standardizedPathname, locale);
     return {
+        pathname,
         unprefixedPathname,
         standardizedPathname,
-        localizedPathname,
     };
 };
 

package/dist/core/src/{core/utils → routing}/pathname/standardize-pathname.js

@@ -1,5 +1,8 @@
-import { PREFIX_PLACEHOLDER } from '../../constants/prefix-placeholder.js';
-import { normalizePathname } from '../normalizers/normalize-pathname.js';
+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 'keyv';
 
 /**
  * Standardizes a canonical pathname by applying the base path

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

@@ -0,0 +1,27 @@
+import { createIntorRuntime } from '../runtime/create-intor-runtime.js';
+
+// Implementation
+async function getTranslator(config, params) {
+    const { readOptions, allowCacheWrite, preKey, handlers, plugins } = params;
+    const locale = params.locale;
+    // Create runtime (request-scoped, no cache write)
+    const runtime = createIntorRuntime(config, {
+        readOptions,
+        allowCacheWrite,
+    });
+    // Ensure messages & create translator snapshot
+    await runtime.ensureMessages(locale);
+    const translator = runtime.translator(locale, {
+        preKey,
+        plugins,
+        handlers,
+    });
+    return {
+        messages: translator.messages,
+        locale,
+        hasKey: translator.hasKey,
+        t: translator.t,
+    };
+}
+
+export { getTranslator };

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

@@ -37,13 +37,13 @@ async function loadMessagesFromUrl(url, options) {
     const fallbackLocales = parseMultiValueParam(url.searchParams.getAll("fallbackLocales"));
     // Load local messages
     return loadLocalMessages({
+        id: options?.id || "default",
         rootDir,
         locale,
         namespaces,
         fallbackLocales,
         concurrency: options?.concurrency,
-        exts: options?.exts,
-        messagesReader: options?.messagesReader,
+        readOptions: options?.readOptions,
         pool: options?.pool,
         cacheOptions: options?.cacheOptions || { enabled: false, ttl: 0 },
         allowCacheWrite: options?.allowCacheWrite,

package/dist/core/src/server/intor/intor.js

@@ -1,53 +1,36 @@
 import '../../core/error/intor-error.js';
-import { deepMerge } from '../../core/utils/deep-merge.js';
-import { resolveLoaderOptions } from '../../core/utils/resolve-loader-options.js';
 import { getLogger } from '../../core/logger/get-logger.js';
 import 'keyv';
-import { loadMessages } from '../messages/load-messages.js';
+import { createIntorRuntime } from '../runtime/create-intor-runtime.js';
 
 /**
- * Entry point for initializing Intor.
+ * Initializes Intor for the current execution context.
  *
- * This function orchestrates the initialization flow:
- *
- * - Resolves the initial locale using a provided locale resolver
- * - Loads locale messages if the message loader is enabled
- * - Returns a fully-initialized Intor result
- *
- * This function does not perform routing decisions itself.
- * Locale resolution is delegated to the provided `getLocale` implementation.
+ * Provides server-side bootstrap logic for SSR-based
+ * full-stack frameworks.
  */
-const intor = async (config, getLocale, loadMessagesOptions = {}) => {
+async function intor(config, localeOrResolver, options) {
     const baseLogger = getLogger(config.logger);
     const logger = baseLogger.child({ scope: "intor" });
     logger.info("Start Intor initialization.");
-    // Resolve initial locale
-    const isLocaleFunction = typeof getLocale === "function";
+    // Create runtime (request-scoped)
+    const runtime = createIntorRuntime(config, options);
+    // Resolve locale
+    const isLocaleFunction = typeof localeOrResolver === "function";
     const locale = isLocaleFunction
-        ? await getLocale(config)
-        : getLocale || config.defaultLocale;
-    const source = typeof getLocale === "function" ? "resolver" : "static";
+        ? await localeOrResolver(config)
+        : localeOrResolver || config.defaultLocale;
+    const source = typeof localeOrResolver === "function" ? "resolver" : "static";
     logger.debug(`Initial locale resolved as "${locale}" via "${source}".`);
-    // Load messages during initialization when a loader is configured.
-    let loadedMessages;
-    const loader = resolveLoaderOptions(config);
-    if (loader) {
-        loadedMessages = await loadMessages({
-            config,
-            locale,
-            extraOptions: {
-                exts: loadMessagesOptions.exts,
-                messagesReader: loadMessagesOptions.messagesReader,
-            },
-            allowCacheWrite: true, // Intor is the primary cache writer during initialization.
-        });
-    }
+    // Ensure messages & create translator snapshot
+    await runtime.ensureMessages(locale);
+    const translator = runtime.translator(locale);
     logger.info("Intor initialized.");
     return {
         config,
-        initialLocale: locale,
-        initialMessages: deepMerge(config.messages, loadedMessages),
+        locale,
+        messages: translator.messages,
     };
-};
+}
 
 export { intor };