为何将bigint转为string的TypeScript函数无法通过类型检查？

我们需要实现一个值清理函数，确保其可安全传入JSON.stringify，为此定义了如下TypeScript代码：

type JsonStringifiable<T> = T extends bigint ? string : T;

function getJsonStringifiableValue<T>(value: T): JsonStringifiable<T> {
    if (typeof value === 'bigint') {
        return `${value}`;
    } else {
        return value;
    }
}

该函数运行行为完全符合预期：

> getJsonStringifiableValue(10n)
'10'
> getJsonStringifiableValue(10)
10
> getJsonStringifiableValue('10')
'10'

但它无法通过类型检查，两处return语句均报错：

if (typeof value === 'bigint') {
    return `${value}`; // ERROR: Type 'string' is not assignable to type 'JsonStringifiable<T>'.
} else {
    return value; // ERROR: Type 'T' is not assignable to type 'JsonStringifiable<T>'.
}

问题原因 #

核心问题在于TypeScript无法在条件分支中正确关联泛型T的具体类型和JsonStringifiable<T>的映射关系：

• 第一个return语句错误：当用typeof value === 'bigint'做类型守卫时，TypeScript能推断当前分支的value是bigint，但无法将这个具体类型回溯到泛型T，也就没法确认此时JsonStringifiable<T>等价于string。JsonStringifiable<T>是依赖泛型的条件类型，编译器不会自动在类型守卫分支中做收缩后的条件类型推导。

• 第二个return语句错误：在else分支中，TypeScript知道value不属于bigint，但同样无法直接确认JsonStringifiable<T>就等于T。条件类型是延迟计算的，只有当T的具体类型确定时才会解析，而函数内部的T仍是未具体化的泛型参数，编译器无法提前验证T满足JsonStringifiable<T> = T。

简单来说，TypeScript的类型系统不会把运行时的类型守卫和泛型条件类型的映射做自动关联，导致编译器无法确认return值的类型和返回值类型JsonStringifiable<T>匹配。

解决方法 #

可以用函数重载明确不同输入对应的返回类型，绕过条件类型的延迟计算问题：

function getJsonStringifiableValue(value: bigint): string;
function getJsonStringifiableValue<T>(value: T): T;
function getJsonStringifiableValue<T>(value: T): T | string {
    if (typeof value === 'bigint') {
        return `${value}`;
    } else {
        return value;
    }
}

重载后，TypeScript能明确识别：输入bigint时返回string，输入其他类型时返回原类型，既保留类型安全性，也能通过类型检查。

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