TypeScript为何无法识别联合类型匹配函数重载？求更优方案

问题代码 #

以下代码无法通过TypeScript编译：

type ReplaceAll2ndArgType = string | ((substring: string, ...args: unknown[]) => string)

export async function renderHTMLTemplate(
    args: Record<string, ReplaceAll2ndArgType>
): Promise<string> {
    let template = "some template text"
    for (const key in args) {
        const val = args[key]
        template = template.replaceAll(`%${key}%`, val)
    }
    return template
}

编译器报错信息 #

No overload matches this call.
  Overload 1 of 2, '(searchValue: string | RegExp, replaceValue: string): string', gave the following error.
    Argument of type 'ReplaceAll2ndArgType' is not assignable to parameter of type 'string'.
      Type '(substring: string, ...args: unknown[]) => string' is not assignable to type 'string'.
  Overload 2 of 2, '(searchValue: string | RegExp, replacer: (substring: string, ...args: any[]) => string): string', gave the following error.
    Argument of type 'ReplaceAll2ndArgType' is not assignable to parameter of type '(substring: string, ...args: any[]) => string'.
      Type 'string' is not assignable to type '(substring: string, ...args: any[]) => string'.

问题根源 #

TypeScript在处理重载函数时，不会自动将联合类型的成员分别匹配到对应的重载签名，而是会检查整个联合类型是否能适配某个单一重载。因此ReplaceAll2ndArgType这个联合类型无法直接满足replaceAll的两个重载要求。

现有临时方案 #

通过typeof分支判断可以绕过编译错误，但写法冗余，且case "function"并未有效收窄类型：

type ReplaceAll2ndArgType = string | ((substring: string, ...args: unknown[]) => string)

export async function renderHTMLTemplate(
    args: Record<string, ReplaceAll2ndArgType>
): Promise<string> {
    let template = "some template text"

    for (const key in args) {
        const val = args[key]
        switch ( typeof val ) {
            case "string":
                template = template.replaceAll(`%${key}%`, val)
                break
            case "function":
                template = template.replaceAll(`%${key}%`, val)
                break
        }
    }
    return template
}

更优解决方法 #

方法1：三元运算符+类型断言 #

利用typeof判断自动收窄字符串类型，函数分支用类型断言明确匹配重载，代码更简洁：

type ReplaceAll2ndArgType = string | ((substring: string, ...args: unknown[]) => string)

export async function renderHTMLTemplate(
    args: Record<string, ReplaceAll2ndArgType>
): Promise<string> {
    let template = "some template text"
    for (const key in args) {
        const val = args[key]
        template = typeof val === "string" 
            ? template.replaceAll(`%${key}%`, val) 
            : template.replaceAll(`%${key}%`, val as (substring: string, ...args: any[]) => string)
    }
    return template
}

方法2：自定义重载辅助函数 #

通过重载辅助函数让TypeScript正确关联联合类型与重载签名，对外类型安全，内部仅需一次类型转换：

type ReplaceAll2ndArgType = string | ((substring: string, ...args: unknown[]) => string)

// 定义重载辅助函数
function replaceTemplate(template: string, key: string, val: string): string
function replaceTemplate(template: string, key: string, val: (substring: string, ...args: unknown[]) => string): string
function replaceTemplate(template: string, key: string, val: ReplaceAll2ndArgType): string {
    return template.replaceAll(`%${key}%`, val as any)
}

export async function renderHTMLTemplate(
    args: Record<string, ReplaceAll2ndArgType>
): Promise<string> {
    let template = "some template text"
    for (const key in args) {
        template = replaceTemplate(template, key, args[key])
    }
    return template
}

方法3：自定义类型守卫（最安全） #

通过类型守卫明确收窄函数类型，无需额外断言，类型检查更严格：

type ReplaceAll2ndArgType = string | ((substring: string, ...args: unknown[]) => string)

// 自定义类型守卫
function isReplaceReplacer(val: ReplaceAll2ndArgType): val is (substring: string, ...args: unknown[]) => string {
    return typeof val === "function"
}

export async function renderHTMLTemplate(
    args: Record<string, ReplaceAll2ndArgType>
): Promise<string> {
    let template = "some template text"
    for (const key in args) {
        const val = args[key]
        if (typeof val === "string") {
            template = template.replaceAll(`%${key}%`, val)
        } else if (isReplaceReplacer(val)) {
            template = template.replaceAll(`%${key}%`, val)
        }
    }
    return template
}

内容的提问来源于stack exchange，提问作者Britton Kerin