SuperAPI AI 工具集

typescript-expert

编程与开发

查看项目

更新于 11-11 17:18

技能介绍

用途与定位

TypeScript Expert 是一个面向 TypeScript 与 JavaScript 开发的高级专家技能,围绕类型级编程、性能优化、monorepo 管理、迁移策略和现代工具链提供实践性指导。它面向真实项目问题,而不是抽象的语言教程。

主要能力

类型系统

  • 品牌类型(Branded Types)用于领域建模,避免原始类型混用,如将 UserId、OrderId 区分为不同名义类型。
  • 高级条件类型与递归类型操作,例如 DeepReadonly、模板字面量类型构建类型安全事件系统。
  • 类型推断技巧,包括使用 satisfies 做约束校验(TS 5.0+)、as const 获取字面量类型。
  • 类型测试:推荐 Vitest 的 expectTypeOf,适用于发布库、复杂泛型函数、类型级工具和 API 契约。

性能优化

  • 使用 npx tsc --extendedDiagnostics --incremental false 诊断类型检查耗时。
  • 常见修复:用接口替代类型交叉、拆分超大联合类型(>100 成员)、避免循环泛型约束、用类型别名打断递归。
  • 构建侧建议:skipLibCheck: true、incremental: true 配合 .tsbuildinfo、精确配置 include/exclude、monorepo 使用带 composite: true 的项目引用。

问题排查

  • 针对“inferred type cannot be named”、“Excessive stack depth comparing types”、缺少类型声明等常见错误给出修复优先级。
  • 模块解析:检查 moduleResolution 与打包工具是否匹配、baseUrl 与 paths 对齐、monorepo 的 workspace 协议、清理缓存。
  • 指出 TypeScript paths 仅在编译期生效,运行时需配合 ts-node 的 tsconfig-paths、loader 或预编译方案。
  • 调试:tsx/ts-node 的 inspect 模式、tsc --traceResolution、tsc --generateTrace 配合 analyze-trace、增大 Node 内存上限。

迁移与工具链

  • JavaScript 转 TypeScript 的增量迁移:先开启 allowJs 与 checkJs,逐步重命名文件、逐文件补类型、逐个启用严格选项;可选 ts-migrate、typesync 辅助。
  • 工具迁移决策表:ESLint+Prettier 转 Biome、TSC 做 lint 转纯类型检查、Lerna 转 Nx/Turborepo、CJS 转 ESM,并标注迁移成本。
  • Biome 与 ESLint 的取舍:Biome 速度快、单工具完成 lint+format、TypeScript 优先,但规则较少且暂不支持类型感知 lint;复杂自定义规则、Vue/Angular 场景建议保留 ESLint。

Monorepo 管理

  • Turborepo 适合结构简单、追求速度、包数量少于 20 的场景;Nx 适合复杂依赖、需要可视化和插件,包数量超过 50 时通常表现更好。
  • 给出根 tsconfig 的项目引用示例,包含 references、composite、declaration、declarationMap。

最佳实践与代码审查

  • 默认严格模式配置示例:strict、noUncheckedIndexedAccess、noImplicitOverride、exactOptionalPropertyTypes、noPropertyAccessFromIndexSignature。
  • ESM 优先:package.json 设置 "type": "module"、必要时使用 .mts、现代工具配置 moduleResolution: bundler、CJS 用动态 import。
  • 代码审查清单覆盖类型安全、最佳实践、性能、模块系统、错误处理、代码组织六个方面。

使用方式

技能被调用后会先做项目探测:确认 tsc 与 node 版本,解析 package.json 识别工具链(biome、eslint、prettier、vitest、jest、turborepo、nx),检测 monorepo 标记文件(pnpm-workspace.yaml、lerna.json、nx.json、turbo.json)。随后匹配现有导入风格与 paths 配置,优先使用项目已有脚本,再定位问题类别并给出方案。验证阶段使用一次性命令:npm run -s typecheck || npx tsc --noEmit、npm test -s || npx vitest run --reporter=basic --no-watch,必要时才运行构建,避免 watch/serve 长驻进程。

适用范围与限制

当问题涉及打包器内部机制时应转交 typescript-build-expert;复杂 ESM/CJS 迁移或循环依赖分析转交 typescript-module-expert;类型性能剖析或编译器内部转交 typescript-type-expert。该技能仅适用于明确匹配上述范围的任务,输出不能替代针对具体环境的验证、测试或专家审查;缺少必要输入、权限、安全边界或成功标准时应先询问澄清。