TypeScript 兼容同步与Promise的函数调用then报类型错误，能否同名重载？

原类型定义的报错根因 #

• 之前使用单联合类型作为入参、返回值的写法，无法在编译期建立“入参形态（同步值/Promise值）→对应返回值形态”的映射关系
• 无论传入的是普通同步值还是Promise值，返回值都会被统一推导为U | Promise<U>的联合类型
• 当调用方尝试直接在返回值上链式调用.then时，TypeScript会校验联合类型下所有成员的方法可用性：如果返回值是同步的U（比如number类型），本身不存在then方法，因此抛出类型错误

同名函数重载实现方案 #

完全不需要拆分两个不同命名的函数，通过TypeScript的函数重载能力，就可以实现入参类型和返回类型的精确匹配，实现一个函数同时覆盖同步、异步两种场景的类型推导。

实现代码 #

// 1. 优先匹配Promise入参的重载（放在前面避免类型推导错位）
export function flow<T, U>(a: Promise<T>, f: (a: T) => U): Promise<U>;
// 2. 匹配普通同步值入参的重载
export function flow<T, U>(a: T, f: (a: T) => U): U;
// 3. 统一实现签名（仅内部逻辑兼容使用，不会对外暴露给调用方做类型匹配）
export function flow<T, U>(a: T | Promise<T>, f: (a: T) => U): U | Promise<U> {
  return a instanceof Promise ? a.then(f) : f(a);
}

推导效果 #

• 传入普通同步值时，TypeScript自动匹配对应重载，返回值被精确推导为纯同步U类型，不会混入Promise相关属性
• 传入Promise值时，自动匹配异步场景重载，返回值被精确推导为Promise<U>类型，可正常链式调用.then方法

调用示例 #

// 同步场景：返回值类型为number，无类型报错
const syncResult = flow(1, (n) => n ** 2);
// 异步场景：返回值类型为Promise<number>，可正常链.then
const asyncResult = flow(Promise.resolve(4), (n) => n ** 2).then(console.log);

注意事项 #

带Promise入参的重载必须放在同步重载的前面。如果顺序颠倒，当入参本身是Promise类型时，会优先匹配“普通值入参”的重载签名，导致T被错误推导为Promise类型，最终返回值的类型完全偏离预期。

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