从 ts-reset 的 `promise-catch` 被移出 `recommended` 说起:TypeScript 接口声明合并的边界与 20 种修复尝试

原创2026-10-13 19:43:181,984 阅读
文章标签:开发工具

从 ts-reset 的 promise-catch 被移出 recommended 说起:TypeScript 接口声明合并的边界与 20 种修复尝试

ts-reset 是 TypeScript 生态中一个"为常见 JavaScript API 打磨类型"的开源项目。其中 promise-catch 入口试图把 Promise 拒绝回调的 reason 参数从 any 收紧为 unknown,但它在 Promise 联合类型(如 Promise<number> | Promise<void>)上会触发"表达式不可调用"的回归,因此最终被排除在 recommended 之外。本文以仓库内 .out-of-scope/promise-catch-in-recommended.md 这一决策文档为主线,完整复盘其背后的类型系统机制、仓库现状,以及维护者为解决它而系统性尝试过的 20 种方案——读完你会理解 TypeScript 接口声明合并"只能加、不能换"的根本限制,并掌握在类似场景下的排查思路与规避手段。

promise-catch 想做什么:把 reason 从 any 收紧为 unknown

在 TypeScript 自带的 lib.es5.d.ts 中,Promise<T> 的 .then() 与 .catch() 拒绝回调参数类型是 any:

// lib.es5.d.ts(简化示意)
catch<TResult = never>(
  onrejected?: ((reason: any) => TResult | PromiseLike<TResult>) | null | undefined,
): Promise<T | TResult>;

any 意味着拒绝回调里的 err 可以不经任何收窄就直接使用,这放过了大量本应在编译期暴露的错误。ts-reset 的 promise-catch 入口正是针对这一点:它通过接口声明合并,给 Promise<T> 追加了一组 reason: unknown 的 .then() / .catch() 重载,强制调用方先收窄类型再使用错误对象。

该入口的真实声明见 src/entrypoints/promise-catch.d.ts,其核心如下:

interface Promise<T> {
  then<TResult1 = T, TResult2 = never>(
    onfulfilled?:
      | ((value: T) => TResult1 | PromiseLike<TResult1>)
      | undefined
      | null,
    onrejected?:
      | ((reason: unknown) => TResult2 | PromiseLike<TResult2>)
      | undefined
      | null,
  ): Promise<TResult1 | TResult2>;

  catch<TResult = never>(
    onrejected?:
      | ((reason: unknown) => TResult | PromiseLike<TResult>)
      | undefined
      | null,
  ): Promise<T | TResult>;
}

这一改动在 CHANGELOG.md 的 0.6.0 版本记录中有直观的"前后对比":

const promise = Promise.reject("error");

// BEFORE:error 是 any!
promise.catch((error) => {
  console.error(error);
});

// AFTER:error 是 unknown!
promise.catch((error) => {
  console.error(error);
});

仓库中还配套了类型级测试 src/tests/promise-catch.ts,用 Expect<Equal<unknown, typeof err>> 断言 .catch() 回调与 .then() 的 onrejected 回调中,err 的类型都必须是 unknown:

import { doNotExecute, Equal, Expect } from "./utils";

doNotExecute(async () => {
  Promise.reject("string instead of Error").catch((err) => {
    type test = Expect<Equal<unknown, typeof err>>;
  });

  Promise.reject("string instead of Error").then(
    () => {},
    (err) => {
      type test = Expect<Equal<unknown, typeof err>>;
    },
  );
});

注意测试通过 doNotExecute 包裹,说明它只做静态类型检查,不真正执行代码——这与 ts-reset 整个项目"纯类型层改动、零运行时成本"的定位一致。

核心决策:为什么它不能进入 recommended

promise-catch 对类型安全是"严格意义上的改进"(strict improvement),但它带来一个破坏性回归:当你在一个 Promise 联合类型上调用 .then() 或 .catch() 时(例如 Promise<number> | Promise<void>),TypeScript 会报错:

This expression is not callable. Each member of the union type '...' has signatures, but none of those signatures are compatible with each other.

机制根源:接口声明合并只能"添加"重载,永远无法"替换"

要理解这个报错,必须先理解 TypeScript 的一个核心规则:接口声明合并(interface declaration merging)只能向类型中添加成员或重载,永远不能移除或替换已有的成员。

这意味着,一旦 ts-reset 声明了 interface Promise<T> { then(...); catch(...); },全局的 Promise<T> 接口上就会同时存在两套 .then() / .catch() 重载:

  1. 一份来自 lib.es5.d.ts 的原始签名(reason: any);
  2. 一份来自 ts-reset 覆盖的签名(reason: unknown)。

当 TypeScript 面对 Promise<number> | Promise<void> 这样的联合类型时,它需要在这些联合成员之间找到一条所有成员都兼容的单一重载签名。而重载被翻倍之后,联合成员之间找不到互相兼容的签名,于是抛出上面的"表达式不可调用"错误。

简言之:promise-catch 想做的每件事——把 reason 从 any 改成 unknown——都只能通过"再叠加一个重载"实现;而叠加重载必然破坏 Promise 联合类型的可调用性。这是 TypeScript 类型系统层面的结构性矛盾,不是某个写法能绕过去的。

仓库中的佐证

  • recommended.d.ts 通过 /// <reference path="..." /> 引用了 fetch、filter-boolean、is-array、json-parse、array-includes、set-has、map-constructor、map-has、array-index-of、map-groupby、object-groupby 共 11 个入口,其中没有 promise-catch;
  • src/entrypoints/promise-catch.d.ts 的注释明确写道"This entrypoint is NOT included in recommended for this reason";
  • CHANGELOG.md 0.7.0 记录:Remove promise-catch from recommended due to incompatibility with promise unions (Promise<A> | Promise<B>)。

现状:保留 opt-in 入口与使用建议

虽然 promise-catch 进不了 recommended,但它对不使用 Promise 联合类型的用户仍然是有价值的安全增强,因此作为独立 opt-in 入口继续保留:

  • package.json 的 exports 映射中仍存在 "./promise-catch" 导出(types 指向 ./dist/promise-catch.d.ts),可供按需导入;
  • 仓库构建脚本 scripts/build.ts 会把 src/entrypoints/*.d.ts 原样拷贝进 dist,因此该入口在发布产物中是完整可用的。

需要此行为的用户,可以显式导入:

import "@total-typescript/ts-reset/promise-catch";

推荐规避方案

如果确实想享受 reason: unknown 的类型安全,又避免联合类型报错,入口声明文件内给出的规避方式是:把 Promise<A> | Promise<B> 换成 Promise<A | B>。联合的 Promise 语义在绝大多数场景下等价于"值的类型是 A 或 B",而后者只有一个 Promise 接口、重载不会翻倍,因此不会触发不可调用错误。

20 种修复尝试的完整复盘

决策文档记录了维护者对这一问题"穷尽式"的调研:先后尝试了 30 余种方案(文档中详述了其中 20 种),无一成功。这些尝试按思路可以归为四类,下面逐一复盘,包括每种方案的思路、代码(如有)与失败原因。

第一类:尝试"替换"掉原始方法签名

这类方案的目标都是让全局 Promise<T> 接口不再携带 lib.es5.d.ts 的原始 .then() / .catch() 签名。

Approach 1:Omit + 交叉类型替换方法

用 Omit<Promise<T>, 'then' | 'catch'> 剥掉原始方法,再与新的签名做交叉(intersection):

type FixedPromise<T> = Omit<Promise<T>, 'then' | 'catch'> & {
  then<TResult1 = T, TResult2 = never>(
    onfulfilled?: ((value: T) => TResult1 | PromiseLike<TResult1>) | null | undefined,
    onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null | undefined,
  ): Promise<TResult1 | TResult2>;
  catch<TResult = never>(
    onrejected?: ((reason: unknown) => TResult | PromiseLike<TResult>) | null | undefined,
  ): Promise<T | TResult>;
};

失败原因有二:一是 Promise<T> 的签名在推导中会引用到包含 Omit<Promise<T>> 的类型,形成循环引用错误;二是即使能编译通过,全局 Promise<T> 也无法被"等于"这个类型别名——你不能用一个类型别名替换一个全局接口。

Approach 2:declare class Promise 重新声明

思路是把 Promise 重新声明为一个类,携带修正后的方法签名。结果直接报 TS2300: Duplicate identifier 'Promise'——TypeScript 不允许对已有的全局声明做二次声明。

Approach 3:declare global { type Promise<T> = ... }

思路是用全局类型别名覆盖 Promise。结果同样是 TS2300: Duplicate identifier 'Promise'——类型别名无法遮蔽已有接口。

Approach 18:映射类型 + as never 键重映射

思路是用映射类型从键集合中排除 then 和 catch,再添加新签名:

// 思路示意
type FixedPromise<T> = {
  [K in keyof Promise<T> as K extends 'then' | 'catch' ? never : K]: Promise<T>[K];
} & { ... };

这套写法作为独立工具类型完全可用,但问题依旧在于:没有任何机制能让全局 Promise<T> 等于一个映射类型。要达成目标就必须替换全局声明,而 TypeScript 不允许这么做。

第二类:利用合并规则与语法形式"钻空子"

这类方案尝试从语法或合并规则的细节入手,希望 TypeScript 能以"替换"而非"叠加"的方式处理新声明。

Approach 4:属性语法代替方法语法

把 then 声明为属性(property)而非方法签名,期待 TypeScript 走"属性替换"而非"重载合并"路径:

interface Promise<T> {
  then: <TResult1 = T, TResult2 = never>(
    onfulfilled?: ((value: T) => TResult1 | PromiseLike<TResult1>) | null | undefined,
    onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null | undefined,
  ) => Promise<TResult1 | TResult2>;
}

结果报 TS2717: Subsequent property declarations must have the same type。TypeScript 强制要求重复声明的属性类型与原始声明完全一致——原始是 any,新声明是 unknown,类型不同,合并被直接拒绝。

Approach 5:完全相同的 any 签名(期待去重)

思路是叠加重载时连 reason: any 都保持一致,期待 TypeScript 识别出完全相同的重载并自动折叠。结果:TypeScript 不会对接口合并产生的相同重载做去重——即使两个重载逐字节相同,联合类型问题依旧存在。

Approach 6:只增强 PromiseLike

既然 Promise<T> 实现了 PromiseLike<T>,那改 PromiseLike 不就行了吗?结果联合类型问题确实消失了(PromiseLike 上只有一个重载),但 Promise 自己有一套独立的 .then() / .catch() 签名(reason: any),增强 PromiseLike 不会传导到 Promise 上——reason 在 Promise 上仍然是 any,违背初衷。

Approach 7:同时增强 PromiseLike 和 Promise

结果:PromiseLike 的增强无济于事,因为 Promise 依旧多了一个重载,双重载问题原样存在。

Approach 8:export {} + declare global 模块模式

思路是把 .d.ts 文件变成一个模块(通过 export {}),再用 declare global { interface Promise<T> { ... } },期待模块上下文改变合并行为。结果:模块作用域的 declare global 与全局环境声明行为完全一致,仍然是叠加重载。

Approach 14:this: Promise<T> 参数约束

思路是在覆盖签名上加 this 参数,期待 TypeScript 更偏好新签名。结果:this 参数并不能阻止双重载问题,两个重载依然同时存在于接口上。

Approach 15:rest 参数元组形式

把命名参数改成 rest 元组形式(...args: [onfulfilled?, onrejected?]),期待产生结构上不同的方法。结果:TypeScript 会把签名归一化,仍然是第二个重载。

Approach 20:添加更多(更简单的)重载

思路是加一些签名更简单的单参数 .then() 重载,或许更容易被联合成员调和。结果完全相反:重载越多,联合问题的组合数越多,问题只会更糟。

第三类:类型层面花式技巧

这类方案试图通过类型运算在"视觉上"或"解析上"让新签名与原始签名变得"相同",从而让 TypeScript 不去叠加。

Approach 9:reason: unknown & {}

用 unknown & {}(排除了 null 和 undefined 的 unknown)代替 unknown,期待产生更"兼容"的重载。结果:现有测试直接失败——Equal<unknown, typeof err> 为 false,因为 unknown & {} 与 unknown 不是同一个类型;而且它同样不解决联合问题。

Approach 10:条件类型(unknown extends any ? unknown : never)

期待条件类型能在编译期求值为 unknown,从而被当作同一个重载。结果:TypeScript 在声明发射(declaration emit)阶段会立即求值该条件类型,它仍然是一个 reason 类型不同的第二个重载。

Approach 11:NoInfer<unknown>

把 unknown 包进 NoInfer<> 工具类型,期待改变类型参数的解析方式。结果:NoInfer<unknown> 解析后就是 unknown,仍然产生一个独立的第二重载。

Approach 12:类型别名间接引用(type _ResetUnknown = unknown)

给 unknown 起个别名再用进签名,期待 TypeScript 把别名当作结构上不同的类型。结果:TypeScript 中的类型别名是透明的,_ResetUnknown 立即解析为 unknown,依旧多出一个重载。

Approach 13:额外类型参数(_TReason = unknown)

给重载签名增加一个类型参数,改变其"元数"(arity),期待 TypeScript 挑选更具体的重载:

then<TResult1 = T, TResult2 = never, _TReason = unknown>(
  onfulfilled?: ((value: T) => TResult1 | PromiseLike<TResult1>) | null | undefined,
  onrejected?: ((reason: _TReason & unknown) => TResult2 | PromiseLike<TResult2>) | null | undefined,
): Promise<TResult1 | TResult2>;

结果:类型参数个数不同让两个重载差异更大,联合问题反而更严重。

第四类:局部修复与构造器方向

Approach 19:只保留 .catch() 覆盖,去掉 .then()

至少先修复 .catch() 的联合场景。结果:.catch() 依然有双重载问题;同时 .then() 的 onrejected 回调丢失了 unknown 类型。即便算作"部分修复",对联合上的 .catch() 依然不可用。

Approach 16:增强 PromiseConstructor.prototype

想直接改内置构造器的原型类型。结果报 TS2687 和 TS2717 错误——不能修改内置构造器的原型类型。

Approach 17:覆盖 PromiseConstructor 的返回类型

让构造器方法返回携带修正签名的类型。结果无效,因为用户代码标注的是 Promise<T>(接口本身),而不是构造器返回的某个具体类型——覆盖构造器返回类型改变不了接口上的重载。

结论:一条走不通的路与三条理论路径

决策文档的最终结论非常明确:这是 TypeScript 类型系统的根本限制。

  • 接口声明合并严格是"加法"——你可以添加成员,但永远不能移除或替换它们;
  • 所有能成功把 reason 改成 unknown 的方案,都是靠叠加第二个重载实现的,而这必然破坏联合兼容性;
  • 所有试图替换原始签名的方案,都被 TypeScript 的"禁止重复声明"规则挡在门外。

两条规则互相锁定,形成了一个在当前 TypeScript 版本下无法解开的死结。文档给出了三条理论上的出路:

  1. 上游改动 TypeScript:把 lib.es5.d.ts 中 Promise .then() / .catch() 的 reason 直接改为 unknown。这是最正确的修复方式,但对整个生态是破坏性变更,TypeScript 团队接受的可能性很低;
  2. 自定义 lib 替换:在 tsconfig 中使用 "lib": [] 并携带打过补丁的 lib 文件。这对 ts-reset 这种"轻量级、即插即用"的定位来说过于沉重;
  3. 未来 TypeScript 特性:如果 TypeScript 未来为接口合并提供"替换而非添加重载"的机制,这个问题可以重新评估。

本次调研的起因是 issue #209("Promise Union - This expression is not callable."),该 issue 也直接引用在 src/entrypoints/promise-catch.d.ts 的注释中。对社区而言,这个"被排除的功能"本身就是一份珍贵的一手教材:它展示了 TypeScript 声明合并的边界在哪里,也展示了在类型系统限制面前,什么叫做"穷尽式排查后做出克制的设计决策"。

仓库内相关证据速查

如果你希望沿着本文继续深入验证,以下是本仓库中与本文主题直接相关的文件:

  • 决策文档:本文主体内容的原始出处,含 20 种方案的完整记录;
  • 入口声明:promise-catch 的真实声明,含 reason: unknown 与已知限制说明;
  • 类型测试:验证 reason 被收紧为 unknown 的 Equal 断言;
  • recommended 入口:11 个默认开启入口的清单,可确认其中没有 promise-catch;
  • 变更日志:0.6.0 引入该规则、0.7.0 将其移出 recommended 的完整时间线;
  • 导出映射:"./promise-catch" 的按需导入入口仍然可用。
登录后查看全文
ts-reset