TypeScript双泛型参数类型收窄：无需类型断言实现预期返回类型

问题描述 #

需要实现一个函数，接收泛型字符串参数index和可选泛型参数language：

• 若language是SupportedLanguage的合法成员，返回${index}_${language}格式的模板字符串类型
• 若language不合法或未传入，返回index本身的类型

当前函数的调用类型符合预期，但实现时无法将language参数收窄为SupportedLanguage类型，出现类型不匹配错误：

Type 'IndexMap<T>[U & "ko"] | IndexMap<T>[U & "ja"] | IndexMap<T>[U & "zh"]' is not assignable to type 'IndexMap<T>[U extends SupportedLanguage ? U : "ko"]'.

解决方案：使用函数重载 #

函数重载可以明确不同参数组合对应的返回类型，让TypeScript能够精准匹配类型逻辑，无需使用类型断言即可解决问题：

export type SupportedLanguage = 'ko' | 'ja' | 'zh'
export const SUPPORTED_LANGUAGES = ['ko', 'ja', 'zh']
interface IndexMap<T extends string> {
  ko: T
  ja: `${T}_ja`
  zh: `${T}_zh`
}

// 重载签名1：不传language参数，返回原始index类型
export function getIndexWithPrefixByLanguage<T extends string>(index: T): T;
// 重载签名2：传入合法的SupportedLanguage，返回带后缀的模板类型
export function getIndexWithPrefixByLanguage<T extends string, U extends SupportedLanguage>(index: T, language: U): IndexMap<T>[U];
// 重载签名3：传入不合法的字符串类型，返回原始index类型
export function getIndexWithPrefixByLanguage<T extends string, U extends string>(index: T, language: U): T;
// 函数实现
export function getIndexWithPrefixByLanguage<T extends string, U extends string>(index: T, language?: U) {
  if (!language || !validateLanguage(language)) {
    return index
  }
  const map: IndexMap<T> = {
    ko: index,
    ja: `${index}_ja`,
    zh: `${index}_zh`,
  }
  // 此时language已被类型守卫收窄为SupportedLanguage，可直接访问map属性
  return map[language]
}

export function validateLanguage(language?: any): language is SupportedLanguage {
  return !!language && SUPPORTED_LANGUAGES.includes(language.toLowerCase())
}

方案说明 #

1. 重载签名明确类型映射：通过三个重载签名分别定义了「无language参数」「合法language参数」「非法language参数」三种场景的输入输出类型，TypeScript会根据调用时的参数自动推断返回类型。
2. 类型守卫正常收窄：在实现逻辑中，validateLanguage类型守卫会将合法的language参数收窄为SupportedLanguage类型，此时访问map[language]的类型会自动匹配对应的重载返回类型，不会出现类型不匹配错误。
3. 无类型断言需求：整个实现过程不需要使用as或!等类型断言，完全依靠TypeScript的类型推断能力保证类型安全。

内容的提问来源于stack exchange，提问作者paul.kim1901