intor 2.2.1 → 2.2.3

package/dist/index.d.cts

@@ -1,8 +1,8 @@
 import { Level, NormalizerConfig, FormatterConfig, LoggerPreset } from 'logry/edge';
-import { Locale, LocaleMessages, FallbackLocalesMap, ScopedLeafKeys, LocalizedLeafKeys, Replacement, TranslateHandlers, LocalizedNodeKeys } from 'intor-translator';
+import { Locale, LocaleMessages, FallbackLocalesMap, NestedMessage, ScopedLeafKeys, LocalizedLeafKeys, Replacement, TranslateHandlers, LocalizedNodeKeys } from 'intor-translator';
 export { FallbackLocalesMap, FormatHandler, LeafKeys, LoadingHandler, Locale, LocaleMessages, LocalizedLeafKeys, LocalizedMessagesUnion, MissingHandler, NestedMessage, NodeKeys, Replacement, ScopedLeafKeys, TranslateHandlerContext, TranslateHandlers, Translator } from 'intor-translator';
-import { Logger } from 'logry';
 import Keyv from 'keyv';
+import { Logger } from 'logry';
 
 type CookieRawOptions = {
     /** Completely disable cookie usage (no read, no write, no lookup by name) - default: false */
@@ -44,28 +44,28 @@ type RouteNamespaces = {
     [key: string]: string[];
     default: string[];
 };
-interface ApiHeaders {
+interface RemoteHeaders {
     authorization?: string;
     "x-api-key"?: string;
     [key: string]: string | undefined;
 }
 type BaseLoaderOptions = {
-    basePath?: string;
+    rootDir?: string;
     namespaces?: string[];
     routeNamespaces?: RouteNamespaces;
     concurrency?: number;
     lazyLoad?: boolean;
 };
-type ImportLoader = BaseLoaderOptions & {
-    type: "import";
+type LocalLoader = BaseLoaderOptions & {
+    type: "local";
 };
-type ApiLoader = BaseLoaderOptions & {
-    type: "api";
-    apiUrl: string;
-    apiHeaders?: ApiHeaders;
+type RemoteLoader = BaseLoaderOptions & {
+    type: "remote";
+    remoteUrl: string;
+    remoteHeaders?: RemoteHeaders;
     fullReload?: boolean;
 };
-type LoaderOptions = ImportLoader | ApiLoader;
+type LoaderOptions = LocalLoader | RemoteLoader;
 
 type LoggerOptions = {
     level?: Level;
@@ -166,40 +166,92 @@ interface IntorResult {
 }
 
 /**
- * Entry point for initializing Intor.
+ * Represents a collection of localized messages.
  *
- * 1. Resolve context via adapter or fallback values.
- * 2. Load messages if loader is enabled.
- * 3. Merge static messages with loaded messages.
+ * - Each key is a namespace or message identifier, and the value is a
+ * `NestedMessage` object that can contain nested message structures.
+ *
+ * @example
+ * ```ts
+ * const messages: Messages = {
+ *   ui: {
+ *     greeting: "Hello",
+ *     farewell: "Goodbye"
+ *   },
+ *   errors: {
+ *     network: "Network error occurred"
+ *   }
+ * };
+ * ```
  */
-declare const intor: (config: IntorResolvedConfig, i18nContext: GetI18nContext | Partial<I18nContext>) => Promise<IntorResult>;
+type Messages = Record<string, NestedMessage>;
+/**
+ * A function that reads messages from a given file path.
+ *
+ * - This function is expected to return a `Promise` that resolves to a `Messages` object.
+ * - It can be implemented to support different file formats such as JSON, YAML, or others.
+ *
+ * @param filePath - The path to the message file to read.
+ * @returns A Promise that resolves to a `Messages` object.
+ *
+ * @example
+ * ```ts
+ * const reader: MessagesReader = async (filePath) => {
+ *   const content = await fs.promises.readFile(filePath, "utf-8");
+ *   return JSON.parse(content) as Messages;
+ * };
+ * ```
+ */
+type MessagesReader = (filePath: string) => Promise<Messages>;
 
-type MessagesLoaderOptions = {
+type LoadMessagesOptions = {
     config: IntorResolvedConfig;
     locale: Locale;
-    pathname: string;
+    pathname?: string;
+    extraOptions?: {
+        exts?: string[];
+        messagesReader?: MessagesReader;
+    };
 };
-type MessagesLoaderResult<C extends GenConfigKeys = "__default__"> = Promise<GenMessages<C> | undefined>;
+type LoadMessagesResult<C extends GenConfigKeys = "__default__"> = Promise<GenMessages<C> | undefined>;
 
 /**
  * Load messages for a given locale and pathname.
  *
  * - Resolve namespaces based on config and pathname.
- * - Support both **local import** and **remote API** loaders.
+ * - Support both **local local** and **remote API** loaders.
  * - Apply fallback locales if needed.
  * - Cache messages if enabled (handled by underlying loader, not this function directly).
  */
-declare const loadMessages: <C extends GenConfigKeys = "__default__">({ config, locale, pathname, }: MessagesLoaderOptions) => MessagesLoaderResult<C>;
+declare const loadMessages: <C extends GenConfigKeys = "__default__">({ config, locale, pathname, extraOptions: { exts, messagesReader }, }: LoadMessagesOptions) => LoadMessagesResult<C>;
+
+/**
+ * Global messages pool (cross-module + hot-reload safe)
+ */
+type MessagesPool = Keyv<LocaleMessages>;
+declare global {
+    var __INTOR_MESSAGES_POOL__: MessagesPool | undefined;
+}
+/**
+ * Optional: clear all cache
+ * Useful in tests or dynamic reloads.
+ */
+declare function clearMessagesPool(): void;
 
 interface LoadLocalMessagesOptions {
-    basePath?: string | null;
-    locale?: string | null;
+    pool?: MessagesPool;
+    rootDir?: string;
+    locale: string;
     fallbackLocales?: string[];
     namespaces?: string[];
-    concurrency?: number;
-    cache?: CacheResolvedOptions;
-    logger?: LoggerOptions & {
-        id: string;
+    extraOptions?: {
+        concurrency?: number;
+        cacheOptions?: CacheResolvedOptions;
+        loggerOptions?: LoggerOptions & {
+            id?: string;
+        };
+        exts?: string[];
+        messagesReader?: MessagesReader;
     };
 }
 
@@ -211,14 +263,21 @@ interface LoadLocalMessagesOptions {
  * - Cache messages if enabled.
  * - Limit concurrent file reads for performance.
  */
-declare const loadLocalMessages: ({ basePath, locale, fallbackLocales, namespaces, concurrency, cache, logger: loggerOptions, }: LoadLocalMessagesOptions) => Promise<LocaleMessages>;
+declare const loadLocalMessages: ({ pool, rootDir, locale, fallbackLocales, namespaces, extraOptions: { concurrency, cacheOptions, loggerOptions, exts, messagesReader, }, }: LoadLocalMessagesOptions) => Promise<LocaleMessages | undefined>;
 
-interface LoadApiMessagesOptions extends Omit<ApiLoader, "type"> {
+interface LoadRemoteMessagesOptions {
+    pool?: MessagesPool;
+    rootDir?: string;
     locale: string;
     fallbackLocales: string[];
-    cache?: CacheResolvedOptions;
-    logger?: LoggerOptions & {
-        id: string;
+    namespaces?: string[];
+    remoteUrl: string;
+    remoteHeaders?: RemoteHeaders;
+    extraOptions?: {
+        cacheOptions?: CacheResolvedOptions;
+        loggerOptions?: LoggerOptions & {
+            id?: string;
+        };
     };
 }
 
@@ -228,7 +287,19 @@ interface LoadApiMessagesOptions extends Omit<ApiLoader, "type"> {
  * - Fetch messages for a target locale with optional fallback locales.
  * - Cache messages if enabled.
  */
-declare const loadApiMessages: <Messages extends LocaleMessages>({ apiUrl, apiHeaders, basePath, locale, fallbackLocales, namespaces, cache, logger: loggerOptions, }: LoadApiMessagesOptions) => Promise<Messages | undefined>;
+declare const loadRemoteMessages: ({ pool, rootDir, remoteUrl, remoteHeaders, locale, fallbackLocales, namespaces, extraOptions: { cacheOptions, loggerOptions, }, }: LoadRemoteMessagesOptions) => Promise<LocaleMessages | undefined>;
+
+/**
+ * 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.
+ */
+declare const intor: (config: IntorResolvedConfig, i18nContext: GetI18nContext | Partial<I18nContext>, loadMessagesOptions?: {
+    exts?: string[];
+    messagesReader?: MessagesReader;
+}) => Promise<IntorResult>;
 
 /** Base properties shared by all translator instances. */
 interface TranslatorBaseProps<M = unknown> {
@@ -284,10 +355,10 @@ declare function getTranslator<CK extends GenConfigKeys = "__default__", PK exte
 }): Promise<TranslatorInstance<GenMessages<CK>, PK>>;
 
 /**
- * Merge static and loaded namespace messages by locale.
- * Loaded messages override static ones on conflict.
+ * Deeply merges loaded messages into static messages by locale.
+ * - Loaded messages override static ones on conflict.
  */
-declare const mergeMessages: (staticMessages?: LocaleMessages, loadedMessages?: LocaleMessages | null) => LocaleMessages;
+declare const mergeMessages: (staticMessages?: LocaleMessages, loadedMessages?: LocaleMessages | undefined) => LocaleMessages;
 
 type RawCacheKey = string | boolean | Array<string | number | boolean | undefined | null>;
 declare const normalizeCacheKey: (key?: RawCacheKey, delimiter?: string) => string | null;
@@ -299,7 +370,7 @@ interface ResolveNamespacesOptions {
 /**
  * Resolves namespaces based on pathname.
  */
-declare const resolveNamespaces: ({ config, pathname, }: ResolveNamespacesOptions) => string[];
+declare const resolveNamespaces: ({ config, pathname, }: ResolveNamespacesOptions) => string[] | undefined;
 
 /**
  * Normalizes and finds the best matching locale from the supported locales list.
@@ -381,17 +452,4 @@ declare global {
  */
 declare function clearLoggerPool(): void;
 
-/**
- * Global messages pool (cross-module + hot-reload safe)
- */
-type MessagesPool = Keyv<LocaleMessages>;
-declare global {
-    var __INTOR_MESSAGES_POOL__: MessagesPool | undefined;
-}
-/**
- * Optional: clear all cache
- * Useful in tests or dynamic reloads.
- */
-declare function clearMessagesPool(): void;
-
-export { type I18nContext, type IntorResult, type LoadApiMessagesOptions, type LoadLocalMessagesOptions, PREFIX_PLACEHOLDER, clearLoggerPool, clearMessagesPool, extractPathname, getTranslator, intor, loadApiMessages, loadLocalMessages, loadMessages, mergeMessages, normalizeCacheKey, normalizeLocale, normalizePathname, resolveNamespaces, resolvePreferredLocale, standardizePathname };
+export { type I18nContext, type IntorResult, type LoadLocalMessagesOptions, type LoadRemoteMessagesOptions, type Messages, type MessagesReader, PREFIX_PLACEHOLDER, clearLoggerPool, clearMessagesPool, extractPathname, getTranslator, intor, loadLocalMessages, loadMessages, loadRemoteMessages, mergeMessages, normalizeCacheKey, normalizeLocale, normalizePathname, resolveNamespaces, resolvePreferredLocale, standardizePathname };

package/dist/index.d.ts

@@ -1,8 +1,8 @@
 import { Level, NormalizerConfig, FormatterConfig, LoggerPreset } from 'logry/edge';
-import { Locale, LocaleMessages, FallbackLocalesMap, ScopedLeafKeys, LocalizedLeafKeys, Replacement, TranslateHandlers, LocalizedNodeKeys } from 'intor-translator';
+import { Locale, LocaleMessages, FallbackLocalesMap, NestedMessage, ScopedLeafKeys, LocalizedLeafKeys, Replacement, TranslateHandlers, LocalizedNodeKeys } from 'intor-translator';
 export { FallbackLocalesMap, FormatHandler, LeafKeys, LoadingHandler, Locale, LocaleMessages, LocalizedLeafKeys, LocalizedMessagesUnion, MissingHandler, NestedMessage, NodeKeys, Replacement, ScopedLeafKeys, TranslateHandlerContext, TranslateHandlers, Translator } from 'intor-translator';
-import { Logger } from 'logry';
 import Keyv from 'keyv';
+import { Logger } from 'logry';
 
 type CookieRawOptions = {
     /** Completely disable cookie usage (no read, no write, no lookup by name) - default: false */
@@ -44,28 +44,28 @@ type RouteNamespaces = {
     [key: string]: string[];
     default: string[];
 };
-interface ApiHeaders {
+interface RemoteHeaders {
     authorization?: string;
     "x-api-key"?: string;
     [key: string]: string | undefined;
 }
 type BaseLoaderOptions = {
-    basePath?: string;
+    rootDir?: string;
     namespaces?: string[];
     routeNamespaces?: RouteNamespaces;
     concurrency?: number;
     lazyLoad?: boolean;
 };
-type ImportLoader = BaseLoaderOptions & {
-    type: "import";
+type LocalLoader = BaseLoaderOptions & {
+    type: "local";
 };
-type ApiLoader = BaseLoaderOptions & {
-    type: "api";
-    apiUrl: string;
-    apiHeaders?: ApiHeaders;
+type RemoteLoader = BaseLoaderOptions & {
+    type: "remote";
+    remoteUrl: string;
+    remoteHeaders?: RemoteHeaders;
     fullReload?: boolean;
 };
-type LoaderOptions = ImportLoader | ApiLoader;
+type LoaderOptions = LocalLoader | RemoteLoader;
 
 type LoggerOptions = {
     level?: Level;
@@ -166,40 +166,92 @@ interface IntorResult {
 }
 
 /**
- * Entry point for initializing Intor.
+ * Represents a collection of localized messages.
  *
- * 1. Resolve context via adapter or fallback values.
- * 2. Load messages if loader is enabled.
- * 3. Merge static messages with loaded messages.
+ * - Each key is a namespace or message identifier, and the value is a
+ * `NestedMessage` object that can contain nested message structures.
+ *
+ * @example
+ * ```ts
+ * const messages: Messages = {
+ *   ui: {
+ *     greeting: "Hello",
+ *     farewell: "Goodbye"
+ *   },
+ *   errors: {
+ *     network: "Network error occurred"
+ *   }
+ * };
+ * ```
  */
-declare const intor: (config: IntorResolvedConfig, i18nContext: GetI18nContext | Partial<I18nContext>) => Promise<IntorResult>;
+type Messages = Record<string, NestedMessage>;
+/**
+ * A function that reads messages from a given file path.
+ *
+ * - This function is expected to return a `Promise` that resolves to a `Messages` object.
+ * - It can be implemented to support different file formats such as JSON, YAML, or others.
+ *
+ * @param filePath - The path to the message file to read.
+ * @returns A Promise that resolves to a `Messages` object.
+ *
+ * @example
+ * ```ts
+ * const reader: MessagesReader = async (filePath) => {
+ *   const content = await fs.promises.readFile(filePath, "utf-8");
+ *   return JSON.parse(content) as Messages;
+ * };
+ * ```
+ */
+type MessagesReader = (filePath: string) => Promise<Messages>;
 
-type MessagesLoaderOptions = {
+type LoadMessagesOptions = {
     config: IntorResolvedConfig;
     locale: Locale;
-    pathname: string;
+    pathname?: string;
+    extraOptions?: {
+        exts?: string[];
+        messagesReader?: MessagesReader;
+    };
 };
-type MessagesLoaderResult<C extends GenConfigKeys = "__default__"> = Promise<GenMessages<C> | undefined>;
+type LoadMessagesResult<C extends GenConfigKeys = "__default__"> = Promise<GenMessages<C> | undefined>;
 
 /**
  * Load messages for a given locale and pathname.
  *
  * - Resolve namespaces based on config and pathname.
- * - Support both **local import** and **remote API** loaders.
+ * - Support both **local local** and **remote API** loaders.
  * - Apply fallback locales if needed.
  * - Cache messages if enabled (handled by underlying loader, not this function directly).
  */
-declare const loadMessages: <C extends GenConfigKeys = "__default__">({ config, locale, pathname, }: MessagesLoaderOptions) => MessagesLoaderResult<C>;
+declare const loadMessages: <C extends GenConfigKeys = "__default__">({ config, locale, pathname, extraOptions: { exts, messagesReader }, }: LoadMessagesOptions) => LoadMessagesResult<C>;
+
+/**
+ * Global messages pool (cross-module + hot-reload safe)
+ */
+type MessagesPool = Keyv<LocaleMessages>;
+declare global {
+    var __INTOR_MESSAGES_POOL__: MessagesPool | undefined;
+}
+/**
+ * Optional: clear all cache
+ * Useful in tests or dynamic reloads.
+ */
+declare function clearMessagesPool(): void;
 
 interface LoadLocalMessagesOptions {
-    basePath?: string | null;
-    locale?: string | null;
+    pool?: MessagesPool;
+    rootDir?: string;
+    locale: string;
     fallbackLocales?: string[];
     namespaces?: string[];
-    concurrency?: number;
-    cache?: CacheResolvedOptions;
-    logger?: LoggerOptions & {
-        id: string;
+    extraOptions?: {
+        concurrency?: number;
+        cacheOptions?: CacheResolvedOptions;
+        loggerOptions?: LoggerOptions & {
+            id?: string;
+        };
+        exts?: string[];
+        messagesReader?: MessagesReader;
     };
 }
 
@@ -211,14 +263,21 @@ interface LoadLocalMessagesOptions {
  * - Cache messages if enabled.
  * - Limit concurrent file reads for performance.
  */
-declare const loadLocalMessages: ({ basePath, locale, fallbackLocales, namespaces, concurrency, cache, logger: loggerOptions, }: LoadLocalMessagesOptions) => Promise<LocaleMessages>;
+declare const loadLocalMessages: ({ pool, rootDir, locale, fallbackLocales, namespaces, extraOptions: { concurrency, cacheOptions, loggerOptions, exts, messagesReader, }, }: LoadLocalMessagesOptions) => Promise<LocaleMessages | undefined>;
 
-interface LoadApiMessagesOptions extends Omit<ApiLoader, "type"> {
+interface LoadRemoteMessagesOptions {
+    pool?: MessagesPool;
+    rootDir?: string;
     locale: string;
     fallbackLocales: string[];
-    cache?: CacheResolvedOptions;
-    logger?: LoggerOptions & {
-        id: string;
+    namespaces?: string[];
+    remoteUrl: string;
+    remoteHeaders?: RemoteHeaders;
+    extraOptions?: {
+        cacheOptions?: CacheResolvedOptions;
+        loggerOptions?: LoggerOptions & {
+            id?: string;
+        };
     };
 }
 
@@ -228,7 +287,19 @@ interface LoadApiMessagesOptions extends Omit<ApiLoader, "type"> {
  * - Fetch messages for a target locale with optional fallback locales.
  * - Cache messages if enabled.
  */
-declare const loadApiMessages: <Messages extends LocaleMessages>({ apiUrl, apiHeaders, basePath, locale, fallbackLocales, namespaces, cache, logger: loggerOptions, }: LoadApiMessagesOptions) => Promise<Messages | undefined>;
+declare const loadRemoteMessages: ({ pool, rootDir, remoteUrl, remoteHeaders, locale, fallbackLocales, namespaces, extraOptions: { cacheOptions, loggerOptions, }, }: LoadRemoteMessagesOptions) => Promise<LocaleMessages | undefined>;
+
+/**
+ * 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.
+ */
+declare const intor: (config: IntorResolvedConfig, i18nContext: GetI18nContext | Partial<I18nContext>, loadMessagesOptions?: {
+    exts?: string[];
+    messagesReader?: MessagesReader;
+}) => Promise<IntorResult>;
 
 /** Base properties shared by all translator instances. */
 interface TranslatorBaseProps<M = unknown> {
@@ -284,10 +355,10 @@ declare function getTranslator<CK extends GenConfigKeys = "__default__", PK exte
 }): Promise<TranslatorInstance<GenMessages<CK>, PK>>;
 
 /**
- * Merge static and loaded namespace messages by locale.
- * Loaded messages override static ones on conflict.
+ * Deeply merges loaded messages into static messages by locale.
+ * - Loaded messages override static ones on conflict.
  */
-declare const mergeMessages: (staticMessages?: LocaleMessages, loadedMessages?: LocaleMessages | null) => LocaleMessages;
+declare const mergeMessages: (staticMessages?: LocaleMessages, loadedMessages?: LocaleMessages | undefined) => LocaleMessages;
 
 type RawCacheKey = string | boolean | Array<string | number | boolean | undefined | null>;
 declare const normalizeCacheKey: (key?: RawCacheKey, delimiter?: string) => string | null;
@@ -299,7 +370,7 @@ interface ResolveNamespacesOptions {
 /**
  * Resolves namespaces based on pathname.
  */
-declare const resolveNamespaces: ({ config, pathname, }: ResolveNamespacesOptions) => string[];
+declare const resolveNamespaces: ({ config, pathname, }: ResolveNamespacesOptions) => string[] | undefined;
 
 /**
  * Normalizes and finds the best matching locale from the supported locales list.
@@ -381,17 +452,4 @@ declare global {
  */
 declare function clearLoggerPool(): void;
 
-/**
- * Global messages pool (cross-module + hot-reload safe)
- */
-type MessagesPool = Keyv<LocaleMessages>;
-declare global {
-    var __INTOR_MESSAGES_POOL__: MessagesPool | undefined;
-}
-/**
- * Optional: clear all cache
- * Useful in tests or dynamic reloads.
- */
-declare function clearMessagesPool(): void;
-
-export { type I18nContext, type IntorResult, type LoadApiMessagesOptions, type LoadLocalMessagesOptions, PREFIX_PLACEHOLDER, clearLoggerPool, clearMessagesPool, extractPathname, getTranslator, intor, loadApiMessages, loadLocalMessages, loadMessages, mergeMessages, normalizeCacheKey, normalizeLocale, normalizePathname, resolveNamespaces, resolvePreferredLocale, standardizePathname };
+export { type I18nContext, type IntorResult, type LoadLocalMessagesOptions, type LoadRemoteMessagesOptions, type Messages, type MessagesReader, PREFIX_PLACEHOLDER, clearLoggerPool, clearMessagesPool, extractPathname, getTranslator, intor, loadLocalMessages, loadMessages, loadRemoteMessages, mergeMessages, normalizeCacheKey, normalizeLocale, normalizePathname, resolveNamespaces, resolvePreferredLocale, standardizePathname };