如何让TypeScript基于同名d.ts校验对应JS文件的类型实现

需求说明 #

• 开发模式偏好：保留原生JavaScript编写运行时代码的习惯，不采用类型与运行时代码混写在.ts文件的经典TS开发模式，仅为各JS模块配套独立的.d.ts类型声明文件，提供类型检查、代码提示能力
• 待实现的校验目标：
  • 开启checkJs后，除了校验引入模块的JS文件的类型使用正确性，还需要让被引入的JS模块本身获得同等级别校验
  • 让TS基于配套的.d.ts声明，识别JS模块的入参类型、校验模块内部的类型使用逻辑
  • 自动校验JS模块的实际实现是否与.d.ts中声明的类型规则匹配
• 示例预期：
  配套声明文件a.d.ts内容如下：

  // a.d.ts
  export function a(val: string): string;
  

  如下错误实现的a.js应当触发两个类型报错：入参为string类型不存在toFixed方法、返回值类型不符合string要求：

  // a.js 错误实现
  export function a(val) {
      return {val: val.toFixed()};
  }
  

  默认配置下TS不会使用同路径的a.d.ts校验对应JS文件，不会抛出任何错误。

实现步骤 #

该需求可以完全实现，无需改动现有JS+d.ts分离的开发模式，仅需调整配置+添加单行注释即可：

• 1. 调整tsconfig.json核心配置
     确保compilerOptions开启以下配置，同时覆盖所有需要校验的JS和d.ts文件：

  {
    "compilerOptions": {
      "allowJs": true,
      "checkJs": true,
      "strict": true,
      "noEmit": true,
      "skipLibCheck": false
    },
    "include": ["src/**/*.js", "src/**/*.d.ts"]
  }
  

  注意：skipLibCheck必须设为false，否则TS会跳过d.ts文件与对应JS实现的关联校验逻辑。

• 2. 在每个JS文件顶部添加单行JSDoc声明，关联同名d.ts文件
     在需要校验的JS文件最顶部添加如下注释，显式指定当前JS文件的类型校验依据为同目录下的同名d.ts文件：

  // @ts-self-types ./a.d.ts
  
  // 后续为原有JS业务代码
  export function a(val) {
    return {val: val.toFixed()};
  }
  

• 3. 校验效果验证
     配置完成后，上述错误的a.js实现会正常抛出两个符合预期的类型错误：
  • 入参val为string类型，不存在toFixed方法
  • 函数返回值为对象类型，不符合声明要求的string类型
    除此之外，JS实现的参数个数、导出成员、方法签名如果和d.ts声明不匹配，也会同步抛出对应校验错误，完全满足预期。

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