intor-translator 1.1.5 → 1.2.1

package/dist/index.d.cts

@@ -1,3 +1,5 @@
+import { RuraHook } from 'rura';
+
 /**
  * A nested message structure or a simple string message.
  *
@@ -186,7 +188,7 @@ type LeafKeys<M, D extends number = DefaultDepth> = [D] extends [never] ? never
  * LocalizedNodeKeys // → string
  * ```
  */
-type LocalizedNodeKeys<M = unknown, L extends keyof M | "union" = "union", D extends number = DefaultDepth> = M extends LocaleMessages ? LocalizedMessagesUnion<M, L> extends NestedMessage ? NodeKeys<LocalizedMessagesUnion<M, L>, D> : never : string;
+type LocalizedNodeKeys<M extends LocaleMessages | undefined = undefined, L extends keyof M | "union" = "union", D extends number = DefaultDepth> = [M] extends [undefined] ? string : L extends "union" ? NodeKeys<M[keyof M], D> : NodeKeys<M[Extract<L, keyof M>], D>;
 /**
  * Extracts all **leaf keys** from the messages
  * of a specified locale (or union of locales).
@@ -209,7 +211,7 @@ type LocalizedNodeKeys<M = unknown, L extends keyof M | "union" = "union", D ext
  * LocalizedLeafKeys // → string
  * ```
  */
-type LocalizedLeafKeys<M = unknown, L extends keyof M | "union" = "union", D extends number = DefaultDepth> = M extends LocaleMessages ? LocalizedMessagesUnion<M, L> extends NestedMessage ? LeafKeys<LocalizedMessagesUnion<M, L>, D> : never : string;
+type LocalizedLeafKeys<M extends LocaleMessages | undefined = undefined, L extends keyof M | "union" = "union", D extends number = DefaultDepth> = [M] extends [undefined] ? string : L extends "union" ? LeafKeys<M[keyof M], D> : LeafKeys<M[Extract<L, keyof M>], D>;
 
 /**
  * Resolves the type at a dot-separated key in a nested object.
@@ -246,51 +248,10 @@ type MessagesAtPreKey<T, PK extends string> = PK extends `${infer Head}.${infer
  */
 type ScopedLeafKeys<M, PK extends string, L extends keyof M | "union" = "union", D extends number = DefaultDepth> = M extends LocaleMessages ? LocalizedMessagesUnion<M, L> extends infer messages ? messages extends NestedMessage ? LeafKeys<MessagesAtPreKey<messages, PK>, D> : never : never : string;
 
-/**
- * A ref object holding all localized messages by locale.
- *
- * @example
- * ```ts
- * const messagesRef: MessagesRef<Messages> = {
- *   current: {
- *     en: { home: { title: "Welcome" } },
- *     zh: { home: { title: "歡迎" } }
- *   }
- * };
- * ```
- */
-type MessagesRef<M = unknown> = {
-    current: Readonly<M>;
-};
-/**
- * A ref object holding the currently selected locale.
- *
- * @example
- * ```ts
- * const localeRef: LocaleRef<Messages> = {
- *   current: "en"
- * };
- * ```
- */
-type LocaleRef<M = unknown> = {
-    current: Locale<M>;
-};
-/**
- * A ref object indicating whether translation is loading.
- *
- * @example
- * ```ts
- * const isLoadingRef: IsLoadingRef = {
- *   current: true
- * };
- * ```
- */
-type IsLoadingRef = {
-    current: boolean;
-};
-
 /**
  * Configuration options for translation behavior.
+ *
+ * @template M - Messages map type.
  */
 type TranslateConfig<M = unknown> = {
     /** Optional mapping of fallback locales to use when a message is missing in the current locale. */
@@ -302,43 +263,66 @@ type TranslateConfig<M = unknown> = {
     /** Optional set of handler functions for customizing translation behavior. */
     handlers?: TranslateHandlers;
 };
-/**
- * Optional handler functions for customizing translation behavior.
- */
+/** Optional handler functions for customizing translation behavior. */
 type TranslateHandlers = {
-    /** Function to format a resolved message before returning it. */
-    formatHandler?: FormatHandler;
     /** Function called when a translation is still loading. */
     loadingHandler?: LoadingHandler;
     /** Function called when no message is found for a given key. */
     missingHandler?: MissingHandler;
+    /** Function to format a resolved message before returning it. */
+    formatHandler?: FormatHandler;
 };
-/** Function to format a resolved message. */
-type FormatHandler<Result = unknown> = (ctx: TranslateHandlerContext & {
-    message: string;
-}) => Result;
 /** Function called when translation is still loading. */
-type LoadingHandler<Result = unknown> = (ctx: TranslateHandlerContext) => Result;
+type LoadingHandler<Result = unknown> = (ctx: HandlerContext) => Result;
 /** Function called when no message is found for the given key. */
-type MissingHandler<Result = unknown> = (ctx: TranslateHandlerContext) => Result;
+type MissingHandler<Result = unknown> = (ctx: HandlerContext) => Result;
+/** Function to format a resolved message. */
+type FormatHandler<Result = unknown> = (ctx: HandlerContext & {
+    rawMessage: string;
+}) => Result;
 /**
- * Context object passed to translation-related functions.
+ * Snapshot of the translate pipeline context exposed to handlers.
  *
- * @example
- * {
- *   locale: "en",
- *   key: "home.title",
- *   replacements: { name: "John" }
- * }
+ * This is a readonly view of TranslateContext:
+ * - Handlers can inspect the translation state
+ * - Handlers must NOT modify it
+ * - Pipeline will not be affected by handler changes
  */
-type TranslateHandlerContext = {
-    /** The current locale being translated. */
-    locale: Locale;
-    /** The translation key for the message. */
+type HandlerContext = Readonly<Omit<TranslateContext, "finalMessage">>;
+
+/**
+ * Context object shared across the translate pipeline.
+ *
+ * @template Result - Final translated value type.
+ */
+interface TranslateContext<Result = unknown> {
+    /** Configuration for the translate pipeline. */
+    config: TranslateConfig;
+    /** Current messages for translation */
+    messages: LocaleMessages;
+    /** Current active locale */
+    locale: string;
+    /** Current loading state */
+    isLoading?: boolean;
+    /** Message key to look up in the messages map */
     key: string;
-    /** Optional replacements for dynamic interpolation in the message. */
+    /** Optional value replacements */
     replacements?: Replacement;
-};
+    /** Ordered list of locales to try, including fallbacks */
+    candidateLocales: string[];
+    /** Raw message string found in the messages map, before formatting */
+    rawMessage?: string;
+    /** Message after formatting (e.g. ICU, custom formatters) */
+    formattedMessage?: unknown;
+    /** Final value produced by the pipeline */
+    finalMessage?: Result;
+    /** Free-form metadata shared between hooks. */
+    meta: Record<string, unknown>;
+}
+/**
+ * A single step in the translate pipeline.
+ */
+type TranslateHook = RuraHook<TranslateContext>;
 
 /**
  * Options for initializing a translator
@@ -362,16 +346,21 @@ interface BaseTranslatorOptions<M = unknown> {
     isLoading?: boolean;
 }
 
-declare class BaseTranslator<M = unknown> {
+/**
+ * The minimal, shared foundation for all translators.
+ *
+ * @template M - Shape of the messages object.
+ */
+declare class BaseTranslator<M extends LocaleMessages> {
     /** Current messages for translation */
-    protected messagesRef: MessagesRef<M>;
+    protected _messages: Readonly<M>;
     /** Current active locale */
-    protected localeRef: LocaleRef<M>;
+    protected _locale: Locale<M>;
     /** Current loading state */
-    protected isLoadingRef: IsLoadingRef;
+    protected _isLoading: boolean;
     constructor(options: BaseTranslatorOptions<M>);
     /** Get messages. */
-    get messages(): M | undefined;
+    get messages(): M;
     /** Get the current active locale. */
     get locale(): Locale<M>;
     /** Get the current loading state. */
@@ -394,27 +383,49 @@ declare class BaseTranslator<M = unknown> {
 }
 
 interface CoreTranslatorOptions<M> extends BaseTranslatorOptions<M>, TranslateConfig<M> {
+    /** Optional plugins or raw hooks to extend the translation pipeline */
+    plugins?: Array<TranslatorPlugin | TranslateHook>;
+}
+interface TranslatorPlugin {
+    /** Optional name for debugging or ordering hints */
+    name?: string;
+    /** One or multiple hooks contributed by this plugin */
+    hook?: TranslateHook | TranslateHook[];
 }
 
-declare class CoreTranslator<M = unknown, L extends keyof M | "union" = "union"> extends BaseTranslator<M> {
-    protected options: CoreTranslatorOptions<M>;
+/**
+ * CoreTranslator provides the default translation behavior
+ * using the pipeline engine and built-in hooks.
+ *
+ * @template M - Shape of the messages object.
+ * @template L - Locale selection strategy ("union" or specific locale keys).
+ */
+declare class CoreTranslator<M extends LocaleMessages, L extends keyof M | "union" = "union"> extends BaseTranslator<M> {
+    /** User-provided options including messages, locale, and config. */
+    protected translateConfig: TranslateConfig<M>;
+    /** Active pipeline hooks applied during translation. */
+    protected hooks: TranslateHook[];
     constructor(options: CoreTranslatorOptions<M>);
+    /** Sort hooks by order value (lower runs earlier). */
+    private sortHooks;
+    /** Register a plugin or a raw pipeline hook. */
+    use(plugin: TranslatorPlugin | TranslateHook): void;
     /** Check if a key exists in the specified locale or current locale. */
-    hasKey: <K = LocalizedLeafKeys<M, L>>(key: K, targetLocale?: Locale<M>) => boolean;
+    hasKey: <K extends LocalizedLeafKeys<M, L>>(key: K, targetLocale?: Locale<M>) => boolean;
     /** Get the translated message for a key, with optional replacements. */
-    t: <Result = string, K = LocalizedLeafKeys<M, L>>(key: K, replacements?: Replacement) => Result;
+    t: <Result = string, K extends LocalizedLeafKeys<M, L> = LocalizedLeafKeys<M, L>>(key: K, replacements?: Replacement) => Result;
 }
 
 type ScopeTranslatorOptions<M> = CoreTranslatorOptions<M>;
-type ScopeTranslatorMethods<M, L extends keyof M | "union" = "union", K = LocalizedLeafKeys<M, L>> = {
+type ScopeTranslatorMethods<M extends LocaleMessages | undefined = undefined, L extends keyof M | "union" = "union", K = LocalizedLeafKeys<M, L>> = {
     hasKey: (key?: K, targetLocale?: Locale<M>) => boolean;
     t: <Result = string>(key?: K, replacements?: Replacement) => Result;
 };
 
-declare class ScopeTranslator<M = unknown, L extends keyof M | "union" = "union"> extends CoreTranslator<M> {
+declare class ScopeTranslator<M extends LocaleMessages, L extends keyof M | "union" = "union"> extends CoreTranslator<M> {
     constructor(options: ScopeTranslatorOptions<M>);
     /** Create a scoped translator with a prefix key, providing `t` and `hasKey` for nested keys. */
     scoped<PK extends LocalizedNodeKeys<M, L> | undefined = undefined>(preKey?: PK): PK extends string ? ScopeTranslatorMethods<M, L, ScopedLeafKeys<M, PK, L>> : ScopeTranslatorMethods<M, L>;
 }
 
-export { type DefaultDepth, type FallbackLocalesMap, type FormatHandler, type IsLoadingRef, type LeafKeys, type LoadingHandler, type Locale, type LocaleMessages, type LocaleRef, type LocalizedLeafKeys, type LocalizedMessagesUnion, type LocalizedNodeKeys, type MessagesRef, type MissingHandler, type NestedMessage, type NodeKeys, type Replacement, ScopeTranslator, type ScopeTranslatorMethods, type ScopeTranslatorOptions, type ScopedLeafKeys, type TranslateHandlerContext, type TranslateHandlers, ScopeTranslator as Translator };
+export { type DefaultDepth, type FallbackLocalesMap, type FormatHandler, type HandlerContext, type LeafKeys, type LoadingHandler, type Locale, type LocaleMessages, type LocalizedLeafKeys, type LocalizedMessagesUnion, type LocalizedNodeKeys, type MissingHandler, type NestedMessage, type NodeKeys, type Replacement, type ScopedLeafKeys, type TranslateConfig, type TranslateContext, type TranslateHandlers, type TranslateHook, ScopeTranslator as Translator, type ScopeTranslatorMethods as TranslatorMethods, type ScopeTranslatorOptions as TranslatorOptions, type TranslatorPlugin };

package/dist/index.d.ts

@@ -1,3 +1,5 @@
+import { RuraHook } from 'rura';
+
 /**
  * A nested message structure or a simple string message.
  *
@@ -186,7 +188,7 @@ type LeafKeys<M, D extends number = DefaultDepth> = [D] extends [never] ? never
  * LocalizedNodeKeys // → string
  * ```
  */
-type LocalizedNodeKeys<M = unknown, L extends keyof M | "union" = "union", D extends number = DefaultDepth> = M extends LocaleMessages ? LocalizedMessagesUnion<M, L> extends NestedMessage ? NodeKeys<LocalizedMessagesUnion<M, L>, D> : never : string;
+type LocalizedNodeKeys<M extends LocaleMessages | undefined = undefined, L extends keyof M | "union" = "union", D extends number = DefaultDepth> = [M] extends [undefined] ? string : L extends "union" ? NodeKeys<M[keyof M], D> : NodeKeys<M[Extract<L, keyof M>], D>;
 /**
  * Extracts all **leaf keys** from the messages
  * of a specified locale (or union of locales).
@@ -209,7 +211,7 @@ type LocalizedNodeKeys<M = unknown, L extends keyof M | "union" = "union", D ext
  * LocalizedLeafKeys // → string
  * ```
  */
-type LocalizedLeafKeys<M = unknown, L extends keyof M | "union" = "union", D extends number = DefaultDepth> = M extends LocaleMessages ? LocalizedMessagesUnion<M, L> extends NestedMessage ? LeafKeys<LocalizedMessagesUnion<M, L>, D> : never : string;
+type LocalizedLeafKeys<M extends LocaleMessages | undefined = undefined, L extends keyof M | "union" = "union", D extends number = DefaultDepth> = [M] extends [undefined] ? string : L extends "union" ? LeafKeys<M[keyof M], D> : LeafKeys<M[Extract<L, keyof M>], D>;
 
 /**
  * Resolves the type at a dot-separated key in a nested object.
@@ -246,51 +248,10 @@ type MessagesAtPreKey<T, PK extends string> = PK extends `${infer Head}.${infer
  */
 type ScopedLeafKeys<M, PK extends string, L extends keyof M | "union" = "union", D extends number = DefaultDepth> = M extends LocaleMessages ? LocalizedMessagesUnion<M, L> extends infer messages ? messages extends NestedMessage ? LeafKeys<MessagesAtPreKey<messages, PK>, D> : never : never : string;
 
-/**
- * A ref object holding all localized messages by locale.
- *
- * @example
- * ```ts
- * const messagesRef: MessagesRef<Messages> = {
- *   current: {
- *     en: { home: { title: "Welcome" } },
- *     zh: { home: { title: "歡迎" } }
- *   }
- * };
- * ```
- */
-type MessagesRef<M = unknown> = {
-    current: Readonly<M>;
-};
-/**
- * A ref object holding the currently selected locale.
- *
- * @example
- * ```ts
- * const localeRef: LocaleRef<Messages> = {
- *   current: "en"
- * };
- * ```
- */
-type LocaleRef<M = unknown> = {
-    current: Locale<M>;
-};
-/**
- * A ref object indicating whether translation is loading.
- *
- * @example
- * ```ts
- * const isLoadingRef: IsLoadingRef = {
- *   current: true
- * };
- * ```
- */
-type IsLoadingRef = {
-    current: boolean;
-};
-
 /**
  * Configuration options for translation behavior.
+ *
+ * @template M - Messages map type.
  */
 type TranslateConfig<M = unknown> = {
     /** Optional mapping of fallback locales to use when a message is missing in the current locale. */
@@ -302,43 +263,66 @@ type TranslateConfig<M = unknown> = {
     /** Optional set of handler functions for customizing translation behavior. */
     handlers?: TranslateHandlers;
 };
-/**
- * Optional handler functions for customizing translation behavior.
- */
+/** Optional handler functions for customizing translation behavior. */
 type TranslateHandlers = {
-    /** Function to format a resolved message before returning it. */
-    formatHandler?: FormatHandler;
     /** Function called when a translation is still loading. */
     loadingHandler?: LoadingHandler;
     /** Function called when no message is found for a given key. */
     missingHandler?: MissingHandler;
+    /** Function to format a resolved message before returning it. */
+    formatHandler?: FormatHandler;
 };
-/** Function to format a resolved message. */
-type FormatHandler<Result = unknown> = (ctx: TranslateHandlerContext & {
-    message: string;
-}) => Result;
 /** Function called when translation is still loading. */
-type LoadingHandler<Result = unknown> = (ctx: TranslateHandlerContext) => Result;
+type LoadingHandler<Result = unknown> = (ctx: HandlerContext) => Result;
 /** Function called when no message is found for the given key. */
-type MissingHandler<Result = unknown> = (ctx: TranslateHandlerContext) => Result;
+type MissingHandler<Result = unknown> = (ctx: HandlerContext) => Result;
+/** Function to format a resolved message. */
+type FormatHandler<Result = unknown> = (ctx: HandlerContext & {
+    rawMessage: string;
+}) => Result;
 /**
- * Context object passed to translation-related functions.
+ * Snapshot of the translate pipeline context exposed to handlers.
  *
- * @example
- * {
- *   locale: "en",
- *   key: "home.title",
- *   replacements: { name: "John" }
- * }
+ * This is a readonly view of TranslateContext:
+ * - Handlers can inspect the translation state
+ * - Handlers must NOT modify it
+ * - Pipeline will not be affected by handler changes
  */
-type TranslateHandlerContext = {
-    /** The current locale being translated. */
-    locale: Locale;
-    /** The translation key for the message. */
+type HandlerContext = Readonly<Omit<TranslateContext, "finalMessage">>;
+
+/**
+ * Context object shared across the translate pipeline.
+ *
+ * @template Result - Final translated value type.
+ */
+interface TranslateContext<Result = unknown> {
+    /** Configuration for the translate pipeline. */
+    config: TranslateConfig;
+    /** Current messages for translation */
+    messages: LocaleMessages;
+    /** Current active locale */
+    locale: string;
+    /** Current loading state */
+    isLoading?: boolean;
+    /** Message key to look up in the messages map */
     key: string;
-    /** Optional replacements for dynamic interpolation in the message. */
+    /** Optional value replacements */
     replacements?: Replacement;
-};
+    /** Ordered list of locales to try, including fallbacks */
+    candidateLocales: string[];
+    /** Raw message string found in the messages map, before formatting */
+    rawMessage?: string;
+    /** Message after formatting (e.g. ICU, custom formatters) */
+    formattedMessage?: unknown;
+    /** Final value produced by the pipeline */
+    finalMessage?: Result;
+    /** Free-form metadata shared between hooks. */
+    meta: Record<string, unknown>;
+}
+/**
+ * A single step in the translate pipeline.
+ */
+type TranslateHook = RuraHook<TranslateContext>;
 
 /**
  * Options for initializing a translator
@@ -362,16 +346,21 @@ interface BaseTranslatorOptions<M = unknown> {
     isLoading?: boolean;
 }
 
-declare class BaseTranslator<M = unknown> {
+/**
+ * The minimal, shared foundation for all translators.
+ *
+ * @template M - Shape of the messages object.
+ */
+declare class BaseTranslator<M extends LocaleMessages> {
     /** Current messages for translation */
-    protected messagesRef: MessagesRef<M>;
+    protected _messages: Readonly<M>;
     /** Current active locale */
-    protected localeRef: LocaleRef<M>;
+    protected _locale: Locale<M>;
     /** Current loading state */
-    protected isLoadingRef: IsLoadingRef;
+    protected _isLoading: boolean;
     constructor(options: BaseTranslatorOptions<M>);
     /** Get messages. */
-    get messages(): M | undefined;
+    get messages(): M;
     /** Get the current active locale. */
     get locale(): Locale<M>;
     /** Get the current loading state. */
@@ -394,27 +383,49 @@ declare class BaseTranslator<M = unknown> {
 }
 
 interface CoreTranslatorOptions<M> extends BaseTranslatorOptions<M>, TranslateConfig<M> {
+    /** Optional plugins or raw hooks to extend the translation pipeline */
+    plugins?: Array<TranslatorPlugin | TranslateHook>;
+}
+interface TranslatorPlugin {
+    /** Optional name for debugging or ordering hints */
+    name?: string;
+    /** One or multiple hooks contributed by this plugin */
+    hook?: TranslateHook | TranslateHook[];
 }
 
-declare class CoreTranslator<M = unknown, L extends keyof M | "union" = "union"> extends BaseTranslator<M> {
-    protected options: CoreTranslatorOptions<M>;
+/**
+ * CoreTranslator provides the default translation behavior
+ * using the pipeline engine and built-in hooks.
+ *
+ * @template M - Shape of the messages object.
+ * @template L - Locale selection strategy ("union" or specific locale keys).
+ */
+declare class CoreTranslator<M extends LocaleMessages, L extends keyof M | "union" = "union"> extends BaseTranslator<M> {
+    /** User-provided options including messages, locale, and config. */
+    protected translateConfig: TranslateConfig<M>;
+    /** Active pipeline hooks applied during translation. */
+    protected hooks: TranslateHook[];
     constructor(options: CoreTranslatorOptions<M>);
+    /** Sort hooks by order value (lower runs earlier). */
+    private sortHooks;
+    /** Register a plugin or a raw pipeline hook. */
+    use(plugin: TranslatorPlugin | TranslateHook): void;
     /** Check if a key exists in the specified locale or current locale. */
-    hasKey: <K = LocalizedLeafKeys<M, L>>(key: K, targetLocale?: Locale<M>) => boolean;
+    hasKey: <K extends LocalizedLeafKeys<M, L>>(key: K, targetLocale?: Locale<M>) => boolean;
     /** Get the translated message for a key, with optional replacements. */
-    t: <Result = string, K = LocalizedLeafKeys<M, L>>(key: K, replacements?: Replacement) => Result;
+    t: <Result = string, K extends LocalizedLeafKeys<M, L> = LocalizedLeafKeys<M, L>>(key: K, replacements?: Replacement) => Result;
 }
 
 type ScopeTranslatorOptions<M> = CoreTranslatorOptions<M>;
-type ScopeTranslatorMethods<M, L extends keyof M | "union" = "union", K = LocalizedLeafKeys<M, L>> = {
+type ScopeTranslatorMethods<M extends LocaleMessages | undefined = undefined, L extends keyof M | "union" = "union", K = LocalizedLeafKeys<M, L>> = {
     hasKey: (key?: K, targetLocale?: Locale<M>) => boolean;
     t: <Result = string>(key?: K, replacements?: Replacement) => Result;
 };
 
-declare class ScopeTranslator<M = unknown, L extends keyof M | "union" = "union"> extends CoreTranslator<M> {
+declare class ScopeTranslator<M extends LocaleMessages, L extends keyof M | "union" = "union"> extends CoreTranslator<M> {
     constructor(options: ScopeTranslatorOptions<M>);
     /** Create a scoped translator with a prefix key, providing `t` and `hasKey` for nested keys. */
     scoped<PK extends LocalizedNodeKeys<M, L> | undefined = undefined>(preKey?: PK): PK extends string ? ScopeTranslatorMethods<M, L, ScopedLeafKeys<M, PK, L>> : ScopeTranslatorMethods<M, L>;
 }
 
-export { type DefaultDepth, type FallbackLocalesMap, type FormatHandler, type IsLoadingRef, type LeafKeys, type LoadingHandler, type Locale, type LocaleMessages, type LocaleRef, type LocalizedLeafKeys, type LocalizedMessagesUnion, type LocalizedNodeKeys, type MessagesRef, type MissingHandler, type NestedMessage, type NodeKeys, type Replacement, ScopeTranslator, type ScopeTranslatorMethods, type ScopeTranslatorOptions, type ScopedLeafKeys, type TranslateHandlerContext, type TranslateHandlers, ScopeTranslator as Translator };
+export { type DefaultDepth, type FallbackLocalesMap, type FormatHandler, type HandlerContext, type LeafKeys, type LoadingHandler, type Locale, type LocaleMessages, type LocalizedLeafKeys, type LocalizedMessagesUnion, type LocalizedNodeKeys, type MissingHandler, type NestedMessage, type NodeKeys, type Replacement, type ScopedLeafKeys, type TranslateConfig, type TranslateContext, type TranslateHandlers, type TranslateHook, ScopeTranslator as Translator, type ScopeTranslatorMethods as TranslatorMethods, type ScopeTranslatorOptions as TranslatorOptions, type TranslatorPlugin };