该技能是一套面向 TypeScript 源码的类型系统规范,建议在阅读或编辑任何 .ts 或 .tsx 文件时使用,并需先应用 type-system-discipline 原则技能。
主要规则与能力:
- 可辨识联合:用 kind 字面量判别字段建模变体,使不可能的状态无法被表示,避免使用可选字段堆叠。
- 品牌类型:用 & { readonly __brand: "X" } 包装基础类型,防止相互混用;在边界处校验一次。
- 构造性建模:通过形状设计让非法值无法被构造,例如 [T, ...T[]] 表示非空、[T, T][] 表示偶数长度、用起点加时长表示范围;它不依赖运行时守卫或精化类型。
- 最简全函数类型:当对 T[] 的每个操作都保持全函数时保留 T[];只在松散类型迫使使用 !、类型断言或“不应发生”抛错时,才强化为 NonEmpty<T>。
- 用 unknown 而非 any:外部数据视为 unknown。
- schema 优先于守卫:手写逐属性类型守卫前,先使用仓库的运行时 schema 库,并从 schema 推断类型,例如 z.infer。
- 禁止 as 断言:每个 as 都是潜在的运行时崩溃点,仅在验证后断言。
- 收窄层级:判别式 switch > in 运算符 > typeof/instanceof > 用户定义类型守卫 > as。
- 类型守卫必须验证其声明:说谎的守卫比 as 更糟,因为 bug 藏在声称安全的名称背后;命名用 isX 或 hasX。
- 穷尽性:在 default 分支内联 const _exhaustive: never = x; 以便新增变体时编译器报错。
- 用 satisfies 而非 as:在不拓宽字面量类型的前提下校验值。
- 边界校验:在数据进入处解析为具名领域类型,Record<string, unknown>(无论何种写法)止于该解析处,内部信任类型。
- 从 schema 派生类型:声明新 interface 前优先使用 Pick/Omit/Parameters/ReturnType/Awaited/typeof。
- 对象参数:传对象而非位置参数,使参数顺序自解释;热路径(逐帧渲染、分词器、解析器)可跳过。
- 真实测试:不要 mock 可以实际运行的组件,优先使用框架真实测试原语并做泄漏/可释放检查,在运行构建中验证 UI;只 mock 本地无法运行的部分。
- 结构化遥测:优先使用带足够上下文的结構化日志诊断,便于从 id 调试;发布代码中不用 console.log。
使用方式:作为技能在编辑 TypeScript 文件时应用上述规则;示例见 references/patterns.md。资料未提供安装命令、收费或价格、平台限制等信息。