TypeScript中回调类型的理想文档化方案（DefinitelyTyped场景）

我正在为一个JavaScript库编写DefinitelyTyped类型定义，库中有大量结构重复的回调函数方法，想用泛型简化重复代码，但遇到了VSCode类型提示不直观的问题。

原有重复代码：

class SomeClass {
  loadResourceTypeA(resourceTypeA: TypeA, options: OptionsType, successCallback: (d: Data) => void, errorCallback: (resource: TypeA, error: Error) => void);
  loadResourceTypeB(resourceTypeB: TypeB, options: OptionsType, successCallback: (d: Data) => void, errorCallback: (resource: TypeB, error: Error) => void);
  loadResourceTypeC(resourceTypeC: TypeC, options: OptionsType, successCallback: (d: Data) => void, errorCallback: (resource: TypeC, error: Error) => void);
}

我尝试用泛型类型别名简化，但VSCode中调用loadResourceTypeA时，类型提示仅显示LoadResource<TypeA>，无法直接看到具体参数信息（只能通过TSDoc查看）：

type LoadResource<T> = (resource: T, options: OptionsType, successCallback: (d: Data) => void, errorCallback: (resource: T, error: Error) => void) => void;

class SomeClass {
  /**
   * @param ...
   */
  loadResourceTypeA: LoadResource<TypeA>;
  /**
   * @param ...
   */
  loadResourceTypeB: LoadResource<TypeB>;
  /**
   * @param ...
   */
  loadResourceTypeC: LoadResource<TypeC>;
}

方案一：使用类型展开工具类型 #

定义一个Expand工具类型，将泛型类型别名展开为具体的函数签名，这样VSCode就能显示完整的参数提示：

// 定义类型展开工具，将函数类型的泛型展开为具体签名
type Expand<T> = T extends (...args: infer Args) => infer Return ? (...args: Args) => Return : T;

type LoadResource<T> = (resource: T, options: OptionsType, successCallback: (d: Data) => void, errorCallback: (resource: T, error: Error) => void) => void;

class SomeClass {
  /**
   * 加载TypeA类型资源
   * @param resourceTypeA TypeA类型的资源实例
   * @param options 加载配置选项
   * @param successCallback 成功回调，返回加载完成的Data数据
   * @param errorCallback 失败回调，返回当前资源实例和错误信息
   */
  loadResourceTypeA: Expand<LoadResource<TypeA>>;
  
  /**
   * 加载TypeB类型资源
   * @param resourceTypeB TypeB类型的资源实例
   * @param options 加载配置选项
   * @param successCallback 成功回调，返回加载完成的Data数据
   * @param errorCallback 失败回调，返回当前资源实例和错误信息
   */
  loadResourceTypeB: Expand<LoadResource<TypeB>>;
  
  /**
   * 加载TypeC类型资源
   * @param resourceTypeC TypeC类型的资源实例
   * @param options 加载配置选项
   * @param successCallback 成功回调，返回加载完成的Data数据
   * @param errorCallback 失败回调，返回当前资源实例和错误信息
   */
  loadResourceTypeC: Expand<LoadResource<TypeC>>;
}

方案二：泛型方法+实例方法别名 #

先定义通用的泛型方法，再为特定类型创建别名，既复用逻辑，又保留完整的参数提示：

declare class SomeClass {
  /**
   * 通用资源加载方法
   * @param resource 要加载的资源实例
   * @param options 加载配置选项
   * @param successCallback 成功回调，返回加载完成的Data数据
   * @param errorCallback 失败回调，返回当前资源实例和错误信息
   */
  loadResource<T>(resource: T, options: OptionsType, successCallback: (d: Data) => void, errorCallback: (resource: T, error: Error) => void): void;

  // 为特定类型创建方法别名，自动继承泛型方法的参数提示
  loadResourceTypeA: typeof this.loadResource<TypeA>;
  loadResourceTypeB: typeof this.loadResource<TypeB>;
  loadResourceTypeC: typeof this.loadResource<TypeC>;
}

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