ts-why-slow

从 tsc --generateTrace 输出中定位最慢的 TypeScript 类型。

English docs: README.md

为什么需要它

TypeScript 大项目性能瓶颈常常来自复杂类型系统，但原始 trace 不易读。 ts-why-slow 会把原始 JSON 转成可执行结论：

• 最慢类型 Top 列表
• 对应位置线索（文件/行号，若可解析）
• 可直接落地的优化建议
• 通过 types.json 做 type id 到可读类型名映射
• 当 trace 事件缺少位置时，回退到 types.json.firstDeclaration

安装

npm i -D ts-why-slow

用法

# 1) 先生成 trace
tsc --generateTrace ./trace-output

# 2) 再分析
npx ts-why-slow ./trace-output

# 3) 常用参数
npx ts-why-slow ./trace-output --top 20 --min-ms 5
npx ts-why-slow ./trace-output --format json > slow-types.json
npx ts-why-slow ./trace-output --format md --output ./slow-types-report.md

如果 TypeScript 6 因为弃用编译选项而阻止生成 trace，可以这样执行：

tsc --generateTrace ./trace-output --ignoreDeprecations 6.0

输出说明

默认表格会展示：

• Duration: 该类型累计耗时
• Share: 在总耗时中的占比
• Hits: 出现次数（用于判断是否是高频慢点）
• Heat: 直观热度条

CLI 参数

• --top : 展示前 n 项（默认 10）
• --min-ms : 过滤低于阈值的项（默认 1）
• --format <table|json|md>: 输出模式（默认 table）
• --output : 将报告写入文件
• --no-color: 关闭彩色输出

推荐排查流程

1. 先看 Share 高且 Hits 高的类型。
2. 优先处理 DeepPartial、递归泛型、超大 union/intersection。
3. 如果热点落在 node_modules/*.d.ts，优先检查第三方库类型是否过深或过宽。
4. 对 <anonymous type> 用 --format json 查看 rawKinds，定位具体表达式热点。
5. 重构后重新生成 trace，对比 json 输出变化。

开发与发布

npm run lint
npm test
npm run build
npm run prepublishOnly

限制

• 不同 TypeScript 版本的 trace 字段可能有差异。
• 即使结合 types.json，仍有部分事件无法给出直接类型名。
• 部分事件没有精确源码位置；工具会在可能时回退到 types.json.firstDeclaration。
• 如果真正的瓶颈来自依赖库类型，位置可能落在第三方 .d.ts 文件。
• 建议为启发式规则，应结合真实回归数据验证。