intor-translator 1.0.8 → 1.0.11

package/dist/index.d.cts

@@ -161,7 +161,7 @@ type LocaleNamespaceMessages = Record<Locale, NamespaceMessages>;
  * type Result = UnionLocaleMessages<typeof messages>;
  * // Result: { auth: { login: "Login" } } | { auth: { logout: "登出" } }
  */
-type UnionLocaleMessages<M extends LocaleNamespaceMessages> = M[LocaleKey<M>];
+type UnionLocaleMessages<M> = M[StrictLocaleKey<M>];
 
 /**
  * Extracts the locale keys from the messages object as string literals.
@@ -173,7 +173,28 @@ type UnionLocaleMessages<M extends LocaleNamespaceMessages> = M[LocaleKey<M>];
  * }>;
  * // Locales is "en" | "zh-TW"
  */
-type LocaleKey<M extends LocaleNamespaceMessages> = keyof M & string;
+type StrictLocaleKey<M> = keyof M & string;
+/**
+ * Extracts locale keys only when M is a valid messages object.
+ *
+ * When M is a concrete `LocaleNamespaceMessages`, the locale key
+ * will be inferred as a union of its top-level keys like `"en" | "zh-TW"`.
+ * Otherwise, falls back to a generic `string`.
+ *
+ * This helps retain intellisense when `messages` is provided,
+ * but avoids TypeScript errors when M is left as `unknown`.
+ *
+ * @example
+ * type Locales = LocaleKey<{
+ *   en: {};
+ *   fr: {};
+ * }>;
+ * //   → "en" | "fr"
+ *
+ * type Fallback = LocaleKey<unknown>;
+ * //   → string
+ */
+type LocaleKey<M = unknown> = M extends LocaleNamespaceMessages ? StrictLocaleKey<M> : string;
 /**
  * A map that defines fallback locales for each base locale.
  *
@@ -242,7 +263,7 @@ type LeafKeys<M, D extends number = DefaultDepth> = [D] extends [never] ? never
  * @example
  * UnionLocaleLeafKeys<{ en: { a: { b: "x" } }, zh: { a: { c: "y" } } }> → "a.b" | "a.c"
  */
-type UnionLocaleLeafKeys<M extends LocaleNamespaceMessages, D extends number = DefaultDepth> = UnionLocaleMessages<M> extends NamespaceMessages ? LeafKeys<UnionLocaleMessages<M>, D> : never;
+type UnionLocaleLeafKeys<M, D extends number = DefaultDepth> = UnionLocaleMessages<M> extends NamespaceMessages ? LeafKeys<UnionLocaleMessages<M>, D> : never;
 /**
  * Resolves the type at a dot-separated key in a nested object.
  *
@@ -261,15 +282,13 @@ type ResolvePathType<T, P extends string> = P extends `${infer Head}.${infer Tai
  * };
  * ScopedLeafKeys<Messages, "auth.login"> → "success" | "failed"
  */
-type ScopedLeafKeys<M extends LocaleNamespaceMessages, K extends string, D extends number = DefaultDepth> = UnionLocaleMessages<M> extends infer ResolvedLocaleMessages ? ResolvedLocaleMessages extends object ? LeafKeys<ResolvePathType<ResolvedLocaleMessages, K>, D> : never : never;
+type ScopedLeafKeys<M, K extends string, D extends number = DefaultDepth> = UnionLocaleMessages<M> extends infer ResolvedLocaleMessages ? ResolvedLocaleMessages extends object ? LeafKeys<ResolvePathType<ResolvedLocaleMessages, K>, D> : never : never;
 /**
  * Infer valid key type from locale messages.
  *
  * If `M` is not passed or empty, fallback to `string`.
  */
-type InferTranslatorKey<M extends LocaleNamespaceMessages> = [
-    M
-] extends [never] ? string : UnionLocaleLeafKeys<M>;
+type InferTranslatorKey<M> = M extends LocaleNamespaceMessages ? UnionLocaleLeafKeys<M> : string;
 
 /**
  * A ref object holding all localized messages by locale.
@@ -282,7 +301,7 @@ type InferTranslatorKey<M extends LocaleNamespaceMessages> = [
  *   }
  * };
  */
-type MessagesRef<M extends LocaleNamespaceMessages> = {
+type MessagesRef<M> = {
     current?: Readonly<M>;
 };
 /**
@@ -293,7 +312,7 @@ type MessagesRef<M extends LocaleNamespaceMessages> = {
  *   current: "en"
  * };
  */
-type LocaleRef<M extends LocaleNamespaceMessages> = {
+type LocaleRef<M> = {
     current?: LocaleKey<M>;
 };
 /**
@@ -309,8 +328,8 @@ type IsLoadingRef = {
 };
 
 /** Config options for translation behavior. */
-type TranslateConfig = {
-    fallbackLocales?: FallbackLocalesMap;
+type TranslateConfig<M> = {
+    fallbackLocales?: FallbackLocalesMap<LocaleKey<M>>;
     loadingMessage?: string;
     placeholder?: string;
     handlers?: TranslateHandlers;
@@ -344,12 +363,12 @@ type TranslateContext = {
     replacements?: Replacement | RichReplacement;
 };
 
-interface BaseTranslatorOptions<M extends LocaleNamespaceMessages> {
+interface BaseTranslatorOptions<M = unknown> {
     messages?: Readonly<M>;
     locale?: LocaleKey<M>;
 }
 
-declare class BaseTranslator<M extends LocaleNamespaceMessages = never> {
+declare class BaseTranslator<M = unknown> {
     protected messagesRef: MessagesRef<M>;
     protected localeRef: LocaleRef<M>;
     constructor(options?: BaseTranslatorOptions<M>);
@@ -370,10 +389,10 @@ declare class BaseTranslator<M extends LocaleNamespaceMessages = never> {
     hasKey: (key: InferTranslatorKey<M>, targetLocale?: LocaleKey<M>) => boolean;
 }
 
-interface CoreTranslatorOptions<M extends LocaleNamespaceMessages> extends BaseTranslatorOptions<M>, TranslateConfig {
+interface CoreTranslatorOptions<M> extends BaseTranslatorOptions<M>, TranslateConfig<M> {
 }
 
-declare class CoreTranslator<M extends LocaleNamespaceMessages = never> extends BaseTranslator<M> {
+declare class CoreTranslator<M = unknown> extends BaseTranslator<M> {
     protected options: CoreTranslatorOptions<M>;
     protected isLoadingRef: IsLoadingRef;
     constructor(options?: CoreTranslatorOptions<M>);
@@ -384,16 +403,16 @@ declare class CoreTranslator<M extends LocaleNamespaceMessages = never> extends
     t: <Result = string>(key: InferTranslatorKey<M>, replacements?: Replacement | RichReplacement) => Result;
 }
 
-declare class ScopeTranslator<M extends LocaleNamespaceMessages = never> extends CoreTranslator<M> {
+declare class ScopeTranslator<M = unknown> extends CoreTranslator<M> {
     constructor(options?: CoreTranslatorOptions<M>);
     scoped<K extends NodeKeys<UnionLocaleMessages<M>> & string>(preKey: K): {
-        hasKey: (key?: ScopedLeafKeys<M, K> & string, targetLocale?: string) => boolean;
+        hasKey: (key?: ScopedLeafKeys<M, K> & string, targetLocale?: LocaleKey<M>) => boolean;
         t: (key?: ScopedLeafKeys<M, K> & string, replacements?: Replacement | RichReplacement) => string;
     };
     scoped(): {
-        hasKey: (key?: UnionLocaleLeafKeys<M> & string, targetLocale?: string) => boolean;
-        t: (key?: UnionLocaleLeafKeys<M> & string, replacements?: Replacement | RichReplacement) => string;
+        hasKey: (key?: InferTranslatorKey<M> & string, targetLocale?: LocaleKey<M>) => boolean;
+        t: (key?: InferTranslatorKey<M> & string, replacements?: Replacement | RichReplacement) => string;
     };
 }
 
-export { type FallbackLocalesMap, type FormatMessage, type IsLoadingRef, type LeafKeys, type Locale, type LocaleKey, type LocaleNamespaceMessages, type LocaleRef, type Message, type MessageRecord, type MessagesRef, type Namespace, type NamespaceMessages, type NestedMessage, type NodeKeys, type OnLoading, type OnMissing, type Replacement, type RichReplacement, type ScopedLeafKeys, type TranslateConfig, type TranslateContext, type TranslateHandlers, ScopeTranslator as Translator, type UnionLocaleLeafKeys, type UnionLocaleMessages };
+export { type FallbackLocalesMap, type FormatMessage, type IsLoadingRef, type LeafKeys, type Locale, type LocaleKey, type LocaleNamespaceMessages, type LocaleRef, type Message, type MessageRecord, type MessagesRef, type Namespace, type NamespaceMessages, type NestedMessage, type NodeKeys, type OnLoading, type OnMissing, type Replacement, type RichReplacement, type ScopedLeafKeys, type StrictLocaleKey, type TranslateConfig, type TranslateContext, type TranslateHandlers, ScopeTranslator as Translator, type UnionLocaleLeafKeys, type UnionLocaleMessages };

package/dist/index.d.ts

@@ -161,7 +161,7 @@ type LocaleNamespaceMessages = Record<Locale, NamespaceMessages>;
  * type Result = UnionLocaleMessages<typeof messages>;
  * // Result: { auth: { login: "Login" } } | { auth: { logout: "登出" } }
  */
-type UnionLocaleMessages<M extends LocaleNamespaceMessages> = M[LocaleKey<M>];
+type UnionLocaleMessages<M> = M[StrictLocaleKey<M>];
 
 /**
  * Extracts the locale keys from the messages object as string literals.
@@ -173,7 +173,28 @@ type UnionLocaleMessages<M extends LocaleNamespaceMessages> = M[LocaleKey<M>];
  * }>;
  * // Locales is "en" | "zh-TW"
  */
-type LocaleKey<M extends LocaleNamespaceMessages> = keyof M & string;
+type StrictLocaleKey<M> = keyof M & string;
+/**
+ * Extracts locale keys only when M is a valid messages object.
+ *
+ * When M is a concrete `LocaleNamespaceMessages`, the locale key
+ * will be inferred as a union of its top-level keys like `"en" | "zh-TW"`.
+ * Otherwise, falls back to a generic `string`.
+ *
+ * This helps retain intellisense when `messages` is provided,
+ * but avoids TypeScript errors when M is left as `unknown`.
+ *
+ * @example
+ * type Locales = LocaleKey<{
+ *   en: {};
+ *   fr: {};
+ * }>;
+ * //   → "en" | "fr"
+ *
+ * type Fallback = LocaleKey<unknown>;
+ * //   → string
+ */
+type LocaleKey<M = unknown> = M extends LocaleNamespaceMessages ? StrictLocaleKey<M> : string;
 /**
  * A map that defines fallback locales for each base locale.
  *
@@ -242,7 +263,7 @@ type LeafKeys<M, D extends number = DefaultDepth> = [D] extends [never] ? never
  * @example
  * UnionLocaleLeafKeys<{ en: { a: { b: "x" } }, zh: { a: { c: "y" } } }> → "a.b" | "a.c"
  */
-type UnionLocaleLeafKeys<M extends LocaleNamespaceMessages, D extends number = DefaultDepth> = UnionLocaleMessages<M> extends NamespaceMessages ? LeafKeys<UnionLocaleMessages<M>, D> : never;
+type UnionLocaleLeafKeys<M, D extends number = DefaultDepth> = UnionLocaleMessages<M> extends NamespaceMessages ? LeafKeys<UnionLocaleMessages<M>, D> : never;
 /**
  * Resolves the type at a dot-separated key in a nested object.
  *
@@ -261,15 +282,13 @@ type ResolvePathType<T, P extends string> = P extends `${infer Head}.${infer Tai
  * };
  * ScopedLeafKeys<Messages, "auth.login"> → "success" | "failed"
  */
-type ScopedLeafKeys<M extends LocaleNamespaceMessages, K extends string, D extends number = DefaultDepth> = UnionLocaleMessages<M> extends infer ResolvedLocaleMessages ? ResolvedLocaleMessages extends object ? LeafKeys<ResolvePathType<ResolvedLocaleMessages, K>, D> : never : never;
+type ScopedLeafKeys<M, K extends string, D extends number = DefaultDepth> = UnionLocaleMessages<M> extends infer ResolvedLocaleMessages ? ResolvedLocaleMessages extends object ? LeafKeys<ResolvePathType<ResolvedLocaleMessages, K>, D> : never : never;
 /**
  * Infer valid key type from locale messages.
  *
  * If `M` is not passed or empty, fallback to `string`.
  */
-type InferTranslatorKey<M extends LocaleNamespaceMessages> = [
-    M
-] extends [never] ? string : UnionLocaleLeafKeys<M>;
+type InferTranslatorKey<M> = M extends LocaleNamespaceMessages ? UnionLocaleLeafKeys<M> : string;
 
 /**
  * A ref object holding all localized messages by locale.
@@ -282,7 +301,7 @@ type InferTranslatorKey<M extends LocaleNamespaceMessages> = [
  *   }
  * };
  */
-type MessagesRef<M extends LocaleNamespaceMessages> = {
+type MessagesRef<M> = {
     current?: Readonly<M>;
 };
 /**
@@ -293,7 +312,7 @@ type MessagesRef<M extends LocaleNamespaceMessages> = {
  *   current: "en"
  * };
  */
-type LocaleRef<M extends LocaleNamespaceMessages> = {
+type LocaleRef<M> = {
     current?: LocaleKey<M>;
 };
 /**
@@ -309,8 +328,8 @@ type IsLoadingRef = {
 };
 
 /** Config options for translation behavior. */
-type TranslateConfig = {
-    fallbackLocales?: FallbackLocalesMap;
+type TranslateConfig<M> = {
+    fallbackLocales?: FallbackLocalesMap<LocaleKey<M>>;
     loadingMessage?: string;
     placeholder?: string;
     handlers?: TranslateHandlers;
@@ -344,12 +363,12 @@ type TranslateContext = {
     replacements?: Replacement | RichReplacement;
 };
 
-interface BaseTranslatorOptions<M extends LocaleNamespaceMessages> {
+interface BaseTranslatorOptions<M = unknown> {
     messages?: Readonly<M>;
     locale?: LocaleKey<M>;
 }
 
-declare class BaseTranslator<M extends LocaleNamespaceMessages = never> {
+declare class BaseTranslator<M = unknown> {
     protected messagesRef: MessagesRef<M>;
     protected localeRef: LocaleRef<M>;
     constructor(options?: BaseTranslatorOptions<M>);
@@ -370,10 +389,10 @@ declare class BaseTranslator<M extends LocaleNamespaceMessages = never> {
     hasKey: (key: InferTranslatorKey<M>, targetLocale?: LocaleKey<M>) => boolean;
 }
 
-interface CoreTranslatorOptions<M extends LocaleNamespaceMessages> extends BaseTranslatorOptions<M>, TranslateConfig {
+interface CoreTranslatorOptions<M> extends BaseTranslatorOptions<M>, TranslateConfig<M> {
 }
 
-declare class CoreTranslator<M extends LocaleNamespaceMessages = never> extends BaseTranslator<M> {
+declare class CoreTranslator<M = unknown> extends BaseTranslator<M> {
     protected options: CoreTranslatorOptions<M>;
     protected isLoadingRef: IsLoadingRef;
     constructor(options?: CoreTranslatorOptions<M>);
@@ -384,16 +403,16 @@ declare class CoreTranslator<M extends LocaleNamespaceMessages = never> extends
     t: <Result = string>(key: InferTranslatorKey<M>, replacements?: Replacement | RichReplacement) => Result;
 }
 
-declare class ScopeTranslator<M extends LocaleNamespaceMessages = never> extends CoreTranslator<M> {
+declare class ScopeTranslator<M = unknown> extends CoreTranslator<M> {
     constructor(options?: CoreTranslatorOptions<M>);
     scoped<K extends NodeKeys<UnionLocaleMessages<M>> & string>(preKey: K): {
-        hasKey: (key?: ScopedLeafKeys<M, K> & string, targetLocale?: string) => boolean;
+        hasKey: (key?: ScopedLeafKeys<M, K> & string, targetLocale?: LocaleKey<M>) => boolean;
         t: (key?: ScopedLeafKeys<M, K> & string, replacements?: Replacement | RichReplacement) => string;
     };
     scoped(): {
-        hasKey: (key?: UnionLocaleLeafKeys<M> & string, targetLocale?: string) => boolean;
-        t: (key?: UnionLocaleLeafKeys<M> & string, replacements?: Replacement | RichReplacement) => string;
+        hasKey: (key?: InferTranslatorKey<M> & string, targetLocale?: LocaleKey<M>) => boolean;
+        t: (key?: InferTranslatorKey<M> & string, replacements?: Replacement | RichReplacement) => string;
     };
 }
 
-export { type FallbackLocalesMap, type FormatMessage, type IsLoadingRef, type LeafKeys, type Locale, type LocaleKey, type LocaleNamespaceMessages, type LocaleRef, type Message, type MessageRecord, type MessagesRef, type Namespace, type NamespaceMessages, type NestedMessage, type NodeKeys, type OnLoading, type OnMissing, type Replacement, type RichReplacement, type ScopedLeafKeys, type TranslateConfig, type TranslateContext, type TranslateHandlers, ScopeTranslator as Translator, type UnionLocaleLeafKeys, type UnionLocaleMessages };
+export { type FallbackLocalesMap, type FormatMessage, type IsLoadingRef, type LeafKeys, type Locale, type LocaleKey, type LocaleNamespaceMessages, type LocaleRef, type Message, type MessageRecord, type MessagesRef, type Namespace, type NamespaceMessages, type NestedMessage, type NodeKeys, type OnLoading, type OnMissing, type Replacement, type RichReplacement, type ScopedLeafKeys, type StrictLocaleKey, type TranslateConfig, type TranslateContext, type TranslateHandlers, ScopeTranslator as Translator, type UnionLocaleLeafKeys, type UnionLocaleMessages };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "intor-translator",
-  "version": "1.0.8",
+  "version": "1.0.11",
   "description": "A type safe translator that knows what to say and how to handle the rest. Supports custom messages, rich replacements, and async loading.",
   "author": "Yiming Liao",
   "license": "MIT",