intor 2.4.17 → 2.5.0

package/dist/express/src/core/messages/utils/is-valid-messages.js

@@ -1,44 +0,0 @@
-/** 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 MessageObject.
- *
- * - Supports all MessageValue variants (primitive, array, object).
- * - Uses an iterative approach to avoid stack overflow.
- */
-function isValidMessages(value) {
-    if (!isPlainObject(value))
-        return false;
-    const stack = [value];
-    while (stack.length > 0) {
-        const current = stack.pop();
-        // primitives are always valid
-        if (current === null ||
-            typeof current === "string" ||
-            typeof current === "number" ||
-            typeof current === "boolean") {
-            continue;
-        }
-        // array → validate each item
-        if (Array.isArray(current)) {
-            for (const item of current) {
-                stack.push(item);
-            }
-            continue;
-        }
-        // object → validate each value
-        if (isPlainObject(current)) {
-            for (const v of Object.values(current)) {
-                stack.push(v);
-            }
-            continue;
-        }
-        // everything else is invalid
-        return false;
-    }
-    return true;
-}
-
-export { isPlainObject, isValidMessages };

package/dist/express/src/core/messages/utils/nest-object-from-path.js

@@ -1,21 +0,0 @@
-/**
- * Wraps a value inside nested objects according to a given path.
- *
- * @example
- * ```ts
- * const value = { a: "A" };
- *
- * nestObjectFromPath(["auth", "verify"], value); // → { auth: { verify: { a: "A" } } }
- *
- * nestObjectFromPath([], value); // →  { a: "A" }
- * ```
- */
-function nestObjectFromPath(path, value) {
-    let obj = value;
-    for (let i = path.length - 1; i >= 0; i--) {
-        obj = { [path[i]]: obj };
-    }
-    return obj;
-}
-
-export { nestObjectFromPath };

package/dist/express/src/core/render/create-html-renderer.js

@@ -1,44 +0,0 @@
-import { escapeHtml } from './utils/escape-html.js';
-import { renderAttributes } from './utils/render-attributes.js';
-
-/**
- * Create an HTML string renderer for semantic rich messages.
- *
- * - Transforms semantic rich AST nodes into escaped HTML strings.
- * - Can be used in any HTML-based environment.
- *
- * This renderer is intentionally minimal and stateless.
- */
-const createHtmlRenderer = (tagRenderers) => {
-    return {
-        /** Render plain text nodes */
-        text(value) {
-            return escapeHtml(value);
-        },
-        /** Render semantic tag nodes */
-        tag(name, attributes, children) {
-            const tagRenderer = tagRenderers?.[name];
-            if (tagRenderer) {
-                return typeof tagRenderer === "function"
-                    ? tagRenderer(children)
-                    : tagRenderer;
-            }
-            // Default behavior: render as native HTML tag
-            return `<${name}${renderAttributes(attributes)}>${children.join("")}</${name}>`;
-        },
-        /** Render raw (non-tokenized) message values as escaped HTML strings */
-        raw(value) {
-            if (value == null)
-                return "";
-            if (typeof value === "string" || typeof value === "number") {
-                return escapeHtml(String(value));
-            }
-            if (Array.isArray(value)) {
-                return value.map((v) => escapeHtml(String(v))).join("");
-            }
-            throw new Error("[intor] HTML renderer cannot render raw non-primitive values.");
-        },
-    };
-};
-
-export { createHtmlRenderer };

package/dist/express/src/core/render/utils/escape-html.js

@@ -1,10 +0,0 @@
-function escapeHtml(value) {
-    return value
-        .replaceAll("&", "&")
-        .replaceAll("<", "&lt;")
-        .replaceAll(">", "&gt;")
-        .replaceAll('"', "&quot;")
-        .replaceAll("'", "&#39;");
-}
-
-export { escapeHtml };

package/dist/express/src/core/render/utils/render-attributes.js

@@ -1,17 +0,0 @@
-import { escapeHtml } from './escape-html.js';
-
-function renderAttributes(attributes) {
-    if (!attributes)
-        return "";
-    return Object.entries(attributes)
-        .map(([key, value]) => {
-        if (value === true)
-            return ` ${key}`;
-        if (value == null)
-            return "";
-        return ` ${key}="${escapeHtml(String(value))}"`;
-    })
-        .join("");
-}
-
-export { renderAttributes };

package/dist/express/src/core/translator/create-t-rich.js

@@ -1,22 +0,0 @@
-import { renderRichMessage } from 'intor-translator';
-import { createHtmlRenderer } from '../render/create-html-renderer.js';
-
-/**
- * Create an HTML-string rich translation function.
- *
- * - Resolves translated messages via `translator.t`
- * - Renders semantic rich tags into escaped HTML strings
- * - Supports optional scoped keys via `preKey`
- *
- * Can be used in any HTML-based environment (Astro, Svelte, SSR, etc.).
- */
-const createTRich = (t) => {
-    return (key, tagRenderers, replacements) => {
-        const message = t(key, replacements);
-        const renderer = createHtmlRenderer(tagRenderers);
-        const nodes = renderRichMessage(message, renderer);
-        return nodes.join("");
-    };
-};
-
-export { createTRich };

package/dist/express/src/core/translator/create-translator.js

@@ -1,30 +0,0 @@
-import { Translator } from 'intor-translator';
-import { mergeMessages } from '../messages/merge-messages.js';
-
-/**
- * Create a server-side Translator instance for a fixed locale.
- *
- * - Merges static config messages with runtime-loaded messages
- * - Initializes a Translator bound to a specific locale
- * - Injects fallback rules, handlers, and plugins from config
- */
-function createTranslator(params) {
-    const { config, locale, messages, handlers, plugins } = params;
-    // Merge static config messages with runtime-loaded messages
-    const finalMessages = mergeMessages(config.messages, messages, {
-        config,
-        locale,
-    });
-    const translator = new Translator({
-        locale,
-        messages: finalMessages,
-        fallbackLocales: config.fallbackLocales,
-        loadingMessage: config.translator?.loadingMessage,
-        missingMessage: config.translator?.missingMessage,
-        handlers,
-        plugins,
-    });
-    return translator;
-}
-
-export { createTranslator };

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

@@ -1,47 +0,0 @@
-/**
- * Deeply merges two plain objects.
- *
- * - Nested plain objects → merged recursively
- * - Arrays / primitives → `b` overwrites `a`
- *
- * 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 = {}, 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))
-            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;
-};
-
-export { deepMerge };

package/dist/express/src/core/utils/normalizers/normalize-cache-key.js

@@ -1,45 +0,0 @@
-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/express/src/core/utils/resolve-loader-options.js

@@ -1,27 +0,0 @@
-/**
- * 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: server
-    // ------------------------------------------------
-    return config.server?.loader ?? config.loader;
-};
-
-export { resolveLoaderOptions };

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

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

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

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

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

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

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

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

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

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

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

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