intor 2.2.14 → 2.2.15

package/dist/src/config/resolvers/resolve-cache-options.js

@@ -0,0 +1,10 @@
+import { DEFAULT_CACHE_OPTIONS } from '../constants/cache.constants.js';
+
+const resolveCacheOptions = (cache) => {
+    return {
+        ...DEFAULT_CACHE_OPTIONS,
+        ...cache,
+    };
+};
+
+export { resolveCacheOptions };

package/dist/src/config/resolvers/resolve-cookie-options.d.ts

@@ -0,0 +1,11 @@
+import type { CookieRawOptions, CookieResolvedOptions } from "../../config/types/cookie.types";
+/**
+ * Resolves the final cookie options by merging the provided options with the default ones.
+ *
+ * This function accepts custom cookie options and merges them with the default values. If no custom options
+ * are provided, the default options will be used. The function returns the resolved cookie options.
+ *
+ * @param cookie - The custom cookie options to override the defaults (optional).
+ * @returns The resolved cookie options, merging the defaults and the provided options.
+ */
+export declare const resolveCookieOptions: (cookie?: CookieRawOptions) => CookieResolvedOptions;

package/dist/src/config/resolvers/resolve-cookie-options.js

@@ -0,0 +1,19 @@
+import { DEFAULT_COOKIE_OPTIONS } from '../constants/cookie.constants.js';
+
+/**
+ * Resolves the final cookie options by merging the provided options with the default ones.
+ *
+ * This function accepts custom cookie options and merges them with the default values. If no custom options
+ * are provided, the default options will be used. The function returns the resolved cookie options.
+ *
+ * @param cookie - The custom cookie options to override the defaults (optional).
+ * @returns The resolved cookie options, merging the defaults and the provided options.
+ */
+const resolveCookieOptions = (cookie = {}) => {
+    return {
+        ...DEFAULT_COOKIE_OPTIONS,
+        ...cookie,
+    };
+};
+
+export { resolveCookieOptions };

package/dist/src/config/resolvers/resolve-fallback-locales.d.ts

@@ -0,0 +1,3 @@
+import type { IntorRawConfig } from "../../config/types/intor-config.types";
+import type { FallbackLocalesMap, Locale } from "intor-translator";
+export declare const resolveFallbackLocales: (config: IntorRawConfig, supportedLocales?: readonly Locale[]) => FallbackLocalesMap;

package/dist/src/config/resolvers/resolve-fallback-locales.js

@@ -0,0 +1,33 @@
+const resolveFallbackLocales = (config, supportedLocales) => {
+    const { defaultLocale, fallbackLocales } = config;
+    if (!fallbackLocales || typeof fallbackLocales !== "object") {
+        return {};
+    }
+    const supportedSet = new Set(supportedLocales);
+    const validMap = {}; // Collected valid fallbacks
+    const invalidFallbackMap = new Map(); // Track invalid ones
+    for (const [locale, fallbacks] of Object.entries(fallbackLocales)) {
+        const fallbackArray = Array.isArray(fallbacks) ? fallbacks : [];
+        // Valid: in supported list, matches default, or literal "default"
+        const validFallbacks = fallbackArray.filter((fallback) => fallback === "default" ||
+            supportedSet.has(fallback) ||
+            fallback === defaultLocale);
+        // Invalid: not "default", not supported, and not defaultLocale
+        const invalidFallbacks = fallbackArray.filter((fallback) => fallback !== "default" &&
+            !supportedSet.has(fallback) &&
+            fallback !== defaultLocale);
+        if (invalidFallbacks.length > 0) {
+            invalidFallbackMap.set(locale, invalidFallbacks);
+        }
+        if (validFallbacks.length > 0) {
+            validMap[locale] = validFallbacks;
+        }
+    }
+    // Log out invalid fallback locales
+    for (const [locale, invalids] of invalidFallbackMap.entries()) {
+        console.warn(`Invalid fallback locales for "${locale}"`, { invalids: [...invalids] }, { scope: "resolveFallbackLocales" });
+    }
+    return validMap;
+};
+
+export { resolveFallbackLocales };

package/dist/src/config/resolvers/resolve-routing-options.d.ts

@@ -0,0 +1,13 @@
+import type { RoutingRawOptions, RoutingResolvedOptions } from "../../config/types/routing.types";
+/**
+ * Resolves routing options by merging default routing options with the provided custom options.
+ * If any specific routing options are not provided, the default values will be used.
+ * The function also normalizes the basePath if provided.
+ *
+ * @param {RoutingRawOptions} [routing={}] - The custom routing options to override the defaults.
+ *   It should be an object that may contain properties like `firstVisit`, `basePath`, etc.
+ *   If not provided, the default values will be used.
+ * @returns {RoutingResolvedOptions} - The resolved routing options, merged from the defaults and provided values.
+ *   This includes the normalized `basePath` and any customized `firstVisit` settings.
+ */
+export declare const resolveRoutingOptions: (routing?: RoutingRawOptions) => RoutingResolvedOptions;

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

@@ -0,0 +1,28 @@
+import { DEFAULT_ROUTING_OPTIONS } from '../constants/routing.constants.js';
+import 'lodash.merge';
+import { normalizePathname } from '../../shared/utils/pathname/normalize-pathname.js';
+
+/**
+ * Resolves routing options by merging default routing options with the provided custom options.
+ * If any specific routing options are not provided, the default values will be used.
+ * The function also normalizes the basePath if provided.
+ *
+ * @param {RoutingRawOptions} [routing={}] - The custom routing options to override the defaults.
+ *   It should be an object that may contain properties like `firstVisit`, `basePath`, etc.
+ *   If not provided, the default values will be used.
+ * @returns {RoutingResolvedOptions} - The resolved routing options, merged from the defaults and provided values.
+ *   This includes the normalized `basePath` and any customized `firstVisit` settings.
+ */
+const resolveRoutingOptions = (routing = {}) => {
+    return {
+        ...DEFAULT_ROUTING_OPTIONS,
+        ...routing,
+        firstVisit: {
+            ...DEFAULT_ROUTING_OPTIONS.firstVisit,
+            ...routing.firstVisit,
+        },
+        basePath: normalizePathname(routing?.basePath || ""),
+    };
+};
+
+export { resolveRoutingOptions };

package/dist/src/config/types/cache.types.d.ts

@@ -0,0 +1,7 @@
+export type CacheRawOptions = {
+    /** default: process.env.NODE_ENV === "production" */
+    enabled?: boolean;
+    /** default: 60\*60\*1000 (1 hour) */
+    ttl?: number;
+};
+export type CacheResolvedOptions = Required<CacheRawOptions>;

package/dist/src/config/types/cookie.types.d.ts

@@ -0,0 +1,23 @@
+export type CookieRawOptions = {
+    /** Enable cookie usage (read/write) - default: true */
+    enabled?: boolean;
+    /** Allow the system to automatically set cookies - default: true */
+    autoSetCookie?: boolean;
+    /** default: "intor.i18n.locale" */
+    name?: string;
+    /** default: null */
+    domain?: string | null;
+    /** default: "/" */
+    path?: string;
+    /** default: 60 * 60 * 24 * 365 (365 days) */
+    maxAge?: number;
+    /** default: false */
+    httpOnly?: boolean;
+    /** default: process.env.NODE_ENV !== "development" */
+    secure?: boolean;
+    /** default: lax */
+    sameSite?: "lax" | "strict" | "none";
+};
+export type CookieResolvedOptions = Required<Omit<CookieRawOptions, "domain">> & {
+    domain: string | null;
+};

package/dist/src/config/types/intor-config.types.d.ts

@@ -0,0 +1,41 @@
+import type { CookieRawOptions, CookieResolvedOptions } from "./cookie.types";
+import type { LoaderOptions } from "./loader.types";
+import type { LoggerOptions } from "./logger.types";
+import type { RoutingRawOptions, RoutingResolvedOptions } from "./routing.types";
+import type { CacheRawOptions, CacheResolvedOptions } from "../../config/types/cache.types";
+import type { TranslatorOptions } from "../../config/types/translator.types";
+import type { FallbackLocalesMap, Locale, LocaleMessages } from "intor-translator";
+export type IntorRawConfig = ({
+    loader: LoaderOptions;
+    supportedLocales: readonly Locale[];
+} | {
+    loader?: undefined;
+    supportedLocales?: readonly Locale[];
+}) & {
+    readonly id?: string;
+    readonly messages?: LocaleMessages;
+    readonly defaultLocale: Locale;
+    readonly fallbackLocales?: FallbackLocalesMap;
+    readonly translator?: TranslatorOptions;
+    readonly cookie?: CookieRawOptions;
+    readonly routing?: RoutingRawOptions;
+    readonly logger?: LoggerOptions;
+    readonly cache?: CacheRawOptions;
+};
+export type IntorResolvedConfig = ({
+    loader: LoaderOptions;
+    supportedLocales: readonly Locale[];
+} | {
+    loader?: undefined;
+    supportedLocales: readonly Locale[];
+}) & {
+    readonly id: string;
+    readonly messages?: LocaleMessages;
+    readonly defaultLocale: Locale;
+    readonly fallbackLocales: FallbackLocalesMap;
+    readonly translator?: TranslatorOptions;
+    readonly cookie: CookieResolvedOptions;
+    readonly routing: RoutingResolvedOptions;
+    readonly logger?: LoggerOptions;
+    readonly cache: CacheResolvedOptions;
+};

package/dist/src/config/types/loader.types.d.ts

@@ -0,0 +1,38 @@
+/**
+ * ```ts
+ * {
+ *  default: ["ui", "meta"],
+ *  "/auth": ["auth", "admin"],
+ * }
+ * // When pathname is "/" => namespaces: ["ui", "meta"]
+ * // When pathname is "/auth" => namespaces: ["ui", "meta", "auth", "admin"]
+ * ```
+ */
+type RouteNamespaces = {
+    [key: string]: string[];
+} | {
+    [key: string]: string[];
+    default: string[];
+};
+export interface RemoteHeaders {
+    authorization?: string;
+    "x-api-key"?: string;
+    [key: string]: string | undefined;
+}
+type BaseLoaderOptions = {
+    rootDir?: string;
+    namespaces?: string[];
+    routeNamespaces?: RouteNamespaces;
+    concurrency?: number;
+};
+type LocalLoader = BaseLoaderOptions & {
+    type: "local";
+};
+type RemoteLoader = BaseLoaderOptions & {
+    type: "remote";
+    remoteUrl: string;
+    remoteHeaders?: RemoteHeaders;
+    fullReload?: boolean;
+};
+export type LoaderOptions = LocalLoader | RemoteLoader;
+export {};

package/dist/src/config/types/logger.types.d.ts

@@ -0,0 +1,7 @@
+import { type FormatterConfig, type Level, type LoggerPreset, type NormalizerConfig } from "logry/edge";
+export type LoggerOptions = {
+    level?: Level;
+    normalizerConfig?: NormalizerConfig;
+    formatterConfig?: FormatterConfig;
+    preset?: LoggerPreset;
+};

package/dist/src/config/types/routing.types.d.ts

@@ -0,0 +1,15 @@
+export declare const routingPrefix: readonly ["none", "all", "except-default"];
+export declare const routingFirstVisitLocaleSource: readonly ["default", "browser"];
+export type RoutingRawOptions = {
+    /** default: "none" */
+    prefix?: (typeof routingPrefix)[number];
+    firstVisit?: {
+        /** default: "browser" */
+        localeSource?: (typeof routingFirstVisitLocaleSource)[number];
+        /** default: true */
+        redirect?: boolean;
+    };
+    /** default: "" */
+    basePath?: string;
+};
+export type RoutingResolvedOptions = Required<RoutingRawOptions>;

package/dist/src/config/types/translator.types.d.ts

@@ -0,0 +1,4 @@
+export type TranslatorOptions = {
+    loadingMessage?: string;
+    placeholder?: string;
+};

package/dist/src/config/validators/validate-default-locale.d.ts

@@ -0,0 +1,3 @@
+import type { IntorRawConfig } from "../../config/types/intor-config.types";
+import type { Locale } from "intor-translator";
+export declare const validateDefaultLocale: (config: IntorRawConfig, supportedLocales: readonly Locale[]) => string;

package/dist/src/config/validators/validate-default-locale.js

@@ -0,0 +1,24 @@
+import { IntorError, IntorErrorCode } from '../../shared/error/intor-error.js';
+
+const validateDefaultLocale = (config, supportedLocales) => {
+    const { id, defaultLocale } = config;
+    // Throw error if defaultLocale is undefined
+    if (!defaultLocale) {
+        throw new IntorError({
+            id,
+            code: IntorErrorCode.MISSING_DEFAULT_LOCALE,
+            message: `The defaultLocale is undefined`,
+        });
+    }
+    // Throw error if defaultLocale is not listed in supportedLocales
+    if (!supportedLocales.includes(defaultLocale)) {
+        throw new IntorError({
+            id,
+            code: IntorErrorCode.UNSUPPORTED_DEFAULT_LOCALE,
+            message: `The defaultLocale "${defaultLocale}" is not included in the supportedLocales.`,
+        });
+    }
+    return defaultLocale;
+};
+
+export { validateDefaultLocale };

package/dist/src/config/validators/validate-supported-locales.d.ts

@@ -0,0 +1,7 @@
+import type { IntorRawConfig } from "../../config/types/intor-config.types";
+/**
+ * Validate and resolve supported locales.
+ * Throws error if loader is used without supportedLocales.
+ * Falls back to message keys if supportedLocales is undefined.
+ */
+export declare const validateSupportedLocales: (config: IntorRawConfig) => readonly string[];

package/dist/src/config/validators/validate-supported-locales.js

@@ -0,0 +1,22 @@
+import { IntorError, IntorErrorCode } from '../../shared/error/intor-error.js';
+
+/**
+ * Validate and resolve supported locales.
+ * Throws error if loader is used without supportedLocales.
+ * Falls back to message keys if supportedLocales is undefined.
+ */
+const validateSupportedLocales = (config) => {
+    const { id, loader, supportedLocales } = config;
+    // Ensure supportedLocales is set when using loader
+    if (loader && !supportedLocales) {
+        throw new IntorError({
+            id,
+            code: IntorErrorCode.MISSING_SUPPORTED_LOCALES,
+            message: `"supportedLocales" is required when using loader, but it is missing.`,
+        });
+    }
+    // Return supportedLocales or infer from message keys
+    return supportedLocales || Object.keys(config.messages || {});
+};
+
+export { validateSupportedLocales };

package/dist/src/server/index.d.ts

@@ -0,0 +1,4 @@
+export { intor, type I18nContext, type IntorResult } from "./intor";
+export { loadMessages, loadLocalMessages, type LoadLocalMessagesOptions, loadRemoteMessages, type LoadRemoteMessagesOptions, type Messages, type MessagesReader, clearMessagesPool, } from "./messages";
+export { getTranslator } from "./translator";
+export { clearLoggerPool } from "./shared/logger/global-logger-pool";

package/dist/src/server/intor/index.d.ts

@@ -0,0 +1,2 @@
+export { intor } from "./intor";
+export type { I18nContext, IntorResult } from "./types";

package/dist/src/server/intor/intor.d.ts

@@ -0,0 +1,14 @@
+import type { IntorResolvedConfig } from "../../config";
+import type { I18nContext, GetI18nContext, IntorResult } from "../../server/intor/types";
+import type { MessagesReader } from "../../server/messages";
+/**
+ * Entry point for initializing Intor.
+ *
+ * 1. Resolve context via adapter or fallback values.
+ * 2. Load messages if loader is enabled.
+ * 3. Merge static messages with loaded messages.
+ */
+export declare const intor: (config: IntorResolvedConfig, i18nContext: GetI18nContext | Partial<I18nContext>, loadMessagesOptions?: {
+    exts?: string[];
+    messagesReader?: MessagesReader;
+}) => Promise<IntorResult>;

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

@@ -0,0 +1,67 @@
+import { loadMessages } from '../messages/load-messages.js';
+import 'node:path';
+import 'node:perf_hooks';
+import 'p-limit';
+import '../../config/constants/cache.constants.js';
+import 'node:fs/promises';
+import { getLogger } from '../shared/logger/get-logger.js';
+import 'lodash.merge';
+import 'keyv';
+import { mergeMessages } from '../../shared/utils/merge-messages.js';
+
+/**
+ * Entry point for initializing Intor.
+ *
+ * 1. Resolve context via adapter or fallback values.
+ * 2. Load messages if loader is enabled.
+ * 3. Merge static messages with loaded messages.
+ */
+const intor = async (config, i18nContext, loadMessagesOptions = {}) => {
+    const baseLogger = getLogger({ id: config.id, ...config.logger });
+    const logger = baseLogger.child({ scope: "intor" });
+    logger.info("Start Intor initialization.");
+    const { messages, loader } = config;
+    const isI18nContextFunction = typeof i18nContext === "function";
+    // 1. Resolve context via adapter or fallback values
+    const context = isI18nContextFunction
+        ? await i18nContext(config)
+        : {
+            locale: (i18nContext?.locale || config.defaultLocale),
+            pathname: i18nContext?.pathname || "",
+        };
+    const { locale, pathname } = context;
+    const source = isI18nContextFunction ? i18nContext.name : "static fallback";
+    logger.debug(`I18n context resolved via ${source}.`, context);
+    // 2. Load messages if loader enabled
+    let loadedMessages;
+    if (loader) {
+        loadedMessages = await loadMessages({
+            config,
+            locale,
+            pathname,
+            extraOptions: {
+                exts: loadMessagesOptions.exts,
+                messagesReader: loadMessagesOptions.messagesReader,
+            },
+            allowCacheWrite: true,
+        });
+    }
+    // 3. Merge static and loaded messages
+    const mergedMessages = mergeMessages(messages, loadedMessages);
+    logger.info("Messages successfully initialized.", {
+        static: { enabled: !!messages },
+        loaded: {
+            enabled: !!loadedMessages,
+            ...(loader ? { loaderType: loader.type } : null),
+        },
+        merged: mergedMessages,
+    });
+    return {
+        config,
+        initialLocale: locale,
+        pathname,
+        messages: mergedMessages,
+    };
+};
+
+export { intor };

package/dist/src/server/intor/types.d.ts

@@ -0,0 +1,14 @@
+import type { IntorResolvedConfig } from "../../config/types/intor-config.types";
+import type { GenLocale } from "../../shared/types/generated.types";
+import type { Locale, LocaleMessages } from "intor-translator";
+export interface I18nContext {
+    locale: GenLocale;
+    pathname: string;
+}
+export type GetI18nContext = (config: IntorResolvedConfig) => Promise<I18nContext>;
+export interface IntorResult {
+    config: IntorResolvedConfig;
+    initialLocale: Locale;
+    pathname: string;
+    messages: LocaleMessages;
+}

package/dist/src/server/messages/index.d.ts

@@ -0,0 +1,7 @@
+export { loadMessages } from "./load-messages";
+export { loadLocalMessages } from "./load-local-messages";
+export type { LoadLocalMessagesOptions } from "./load-local-messages";
+export { loadRemoteMessages } from "./load-remote-messages";
+export type { LoadRemoteMessagesOptions } from "./load-remote-messages";
+export type { Messages, MessagesReader } from "./shared/types";
+export { clearMessagesPool } from "./shared/global-messages-pool";

package/dist/src/server/messages/load-local-messages/index.d.ts

@@ -0,0 +1,2 @@
+export type { LoadLocalMessagesOptions } from "./types";
+export { loadLocalMessages } from "./load-local-messages";

package/dist/src/server/messages/load-local-messages/load-local-messages.d.ts

@@ -0,0 +1,11 @@
+import type { LoadLocalMessagesOptions } from "./types";
+import type { LocaleMessages } from "intor-translator";
+/**
+ * Load local messages from the file system.
+ *
+ * - Load messages for a target locale with optional fallback locales.
+ * - Support filtering by specific namespaces.
+ * - Cache messages if enabled.
+ * - Limit concurrent file reads for performance.
+ */
+export declare const loadLocalMessages: ({ pool, rootDir, locale, fallbackLocales, namespaces, extraOptions: { concurrency, cacheOptions, loggerOptions, exts, messagesReader, }, allowCacheWrite, }: LoadLocalMessagesOptions) => Promise<LocaleMessages | undefined>;

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

@@ -0,0 +1,85 @@
+import path from 'node:path';
+import { performance } from 'node:perf_hooks';
+import pLimit from 'p-limit';
+import { DEFAULT_CACHE_OPTIONS } from '../../../config/constants/cache.constants.js';
+import { readLocaleMessages } from './read-locale-messages/read-locale-messages.js';
+import { getGlobalMessagesPool } from '../shared/global-messages-pool.js';
+import { getLogger } from '../../shared/logger/get-logger.js';
+import 'lodash.merge';
+import { normalizeCacheKey } from '../../../shared/utils/normalize-cache-key.js';
+
+/**
+ * Load local messages from the file system.
+ *
+ * - Load messages for a target locale with optional fallback locales.
+ * - Support filtering by specific namespaces.
+ * - Cache messages if enabled.
+ * - Limit concurrent file reads for performance.
+ */
+const loadLocalMessages = async ({ pool = getGlobalMessagesPool(), rootDir = "messages", locale, fallbackLocales, namespaces, extraOptions: { concurrency = 10, cacheOptions = DEFAULT_CACHE_OPTIONS, loggerOptions = { id: "default" }, exts, messagesReader, } = {}, allowCacheWrite = false, }) => {
+    const baseLogger = getLogger({ ...loggerOptions });
+    const logger = baseLogger.child({ scope: "load-local-messages" });
+    // Start performance measurement
+    const start = performance.now();
+    logger.debug("Loading local messages from directory.", {
+        rootDir,
+        resolvedRootDir: path.resolve(process.cwd(), rootDir),
+    });
+    //====== Cache lookup ======
+    const key = normalizeCacheKey([
+        loggerOptions.id,
+        "loaderType:local",
+        rootDir,
+        locale,
+        (fallbackLocales || []).toSorted().join(","),
+        (namespaces || []).toSorted().join(","),
+    ]);
+    if (cacheOptions.enabled && key) {
+        const cached = await pool?.get(key);
+        if (cached) {
+            logger.debug("Messages cache hit.", { key });
+            return cached;
+        }
+    }
+    //============================================================
+    // Read messages
+    //============================================================
+    const limit = pLimit(concurrency);
+    const candidateLocales = [locale, ...(fallbackLocales || [])];
+    let messages;
+    for (const candidateLocale of candidateLocales) {
+        try {
+            const result = await readLocaleMessages({
+                limit,
+                rootDir,
+                locale: candidateLocale,
+                namespaces,
+                extraOptions: { loggerOptions, exts, messagesReader },
+            });
+            if (result && Object.values(result[candidateLocale] || {}).length > 0) {
+                messages = result;
+                break;
+            }
+        }
+        catch (error) {
+            logger.error("Failed to read locale messages", {
+                locale: candidateLocale,
+                error,
+            });
+        }
+    }
+    //====== Cache storage ======
+    if (allowCacheWrite && cacheOptions.enabled && key && messages) {
+        await pool?.set(key, messages, cacheOptions.ttl);
+    }
+    // Log out validnamespaces & performance measurement
+    const end = performance.now();
+    const duration = Math.round(end - start);
+    logger.trace("Finished loading local messages.", {
+        loadedLocale: messages ? Object.keys(messages)[0] : undefined,
+        duration: `${duration} ms`,
+    });
+    return messages;
+};
+
+export { loadLocalMessages };

package/dist/src/server/messages/load-local-messages/read-locale-messages/collect-file-entries/collect-file-entries.d.ts

@@ -0,0 +1,29 @@
+import type { CollectFileEntriesOptions } from "./types";
+import type { FileEntry } from "../../../../../server/messages/load-local-messages/read-locale-messages";
+/**
+ * Recursively collects all message files under a given root directory.
+ *
+ * - Supports filtering by allowed file extensions and optional namespaces.
+ * - Processes directories concurrently using the provided `limit` function.
+ *
+ * @example
+ * ```ts
+ * [
+ *   {
+ *     namespace: "index", // "index" = messages under locale root (no namespace)
+ *     fullPath: "/Users/john/my-app/messages/en-US/index.json",
+ *     relativePath: "index.json",
+ *     segments: ["index"],
+ *     basename: "index",
+ *   },
+ *   {
+ *     namespace: "auth",
+ *     fullPath: "/Users/john/my-app/messages/en-US/auth/login.json",
+ *     relativePath: "auth/login.json",
+ *     segments: ["auth", "login"],
+ *     basename: "login",
+ *   },
+ * ];
+ * ```
+ */
+export declare function collectFileEntries({ readdir, limit, rootDir, namespaces, extraOptions: { exts, loggerOptions }, }: CollectFileEntriesOptions): Promise<FileEntry[]>;