如何解决TypeScript类型系统与运行时行为的不一致问题？

问题分析 #

你定义的Awaitable<T>试图通过排除自身为thenable的T，来保证Awaited<Awaitable<T>>等价于T，但这个逻辑存在漏洞：

• 当一个值同时满足T类型和PromiseLike<U>（且U≠T）时，会被Awaitable<T>错误地接受。TypeScript的结构类型系统无法识别then方法实际会返回与T不符的值，导致类型推导结果和运行时行为脱节。
• 示例中something既是{data: true}类型，又是PromiseLike<{data: false}>，赋值给Awaitable<{data: true}>时类型检查通过，但await后实际得到{data: false}，与类型推导的{data: true}矛盾。
• AcceptsAwaitable函数的返回值声明为Promise<T>，但实际可能返回Promise<U>，完全不符合预期。

解决方案 #

修正Awaitable定义 #

调整Awaitable<T>的逻辑，确保它只包含两类值：非PromiseLike的T，或者严格的PromiseLike，避免中间态的混入：

export type Awaitable<T> = 
  | (T extends PromiseLike<any> ? never : T)
  | PromiseLike<T>;

这个定义的作用：

1. (T extends PromiseLike<any> ? never : T)分支：排除自身就是PromiseLike的T，避免重复嵌套（比如Awaitable<Promise<T>>不会变成Promise<T> | PromiseLike<Promise<T>>）。
2. PromiseLike<T>分支：只接受符合PromiseLike规范的值，即then方法的回调参数必须是T类型，从根源上阻止了像示例中PromiseLike<{data: false}>被错误归类到Awaitable<{data: true}>的情况。

验证修正效果 #

• 示例中something不再能赋值给Awaitable<{data: true}>，因为它的then方法回调参数是{data: false}，不满足PromiseLike<{data: true}>的要求，类型检查会提前报错，避免后续运行时与类型不符的问题。
• AcceptsAwaitable函数的返回值现在能严格匹配Promise<T>：因为awaitable要么是T（非PromiseLike），要么是PromiseLike<T>，await后必然得到T，返回值类型完全正确。

简化版（若无需排除T自身为PromiseLike的情况） #

如果你不需要避免T本身是PromiseLike的场景，也可以直接用最简定义：

export type Awaitable<T> = T | PromiseLike<T>;

但这种情况下，若传入一个既是T又是PromiseLike<U>（U≠T）的值，依然会出现类型与运行时不符的问题，仅适合能保证不会出现此类值的场景。

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