typescript-best-practices

TypeScript 最佳实践

请先应用 type-system-discipline 原则技能；该技能将此原则落实到 TypeScript 语法中。

规则	概要
可辨识联合	使用 kind 字面量判别字段对变体建模，确保无法表示不可能的状态。不要使用包含可选字段的对象。
品牌类型	使用 & { readonly __brand: "X" } 为原始类型添加品牌，避免混淆。创建时验证一次。
优先使用 unknown，而非 any	外部数据的类型是 unknown。any 会在所有涉及它的地方禁用类型检查。
不使用 as 类型断言	每个 as 都可能引发运行时崩溃。仅在验证后才进行类型断言。
类型收窄层级	判别字段 switch > in 运算符 > typeof/instanceof > 用户定义的类型守卫 > as。
类型守卫	必须验证所声明的判断。说谎的类型守卫比 as 更糟糕，因为错误会藏在一个看似安全的名称后面。将其命名为 isX 或 hasX。
穷尽性检查	在 default 分支中内联 const _exhaustive: never = x;，这样添加新变体时编译器就会报错。
优先使用 satisfies，而非 as	验证值，同时避免扩大字面量类型。
边界验证	在数据进入系统时验证；在内部信任类型。参见 boundary-discipline 原则技能。
从 schema 派生类型	声明新接口前，优先考虑使用 Pick/Omit/Parameters/ReturnType/Awaited/typeof。
对象参数	传递对象而非位置参数，让参数顺序一目了然。在高频路径中除外（逐帧渲染、分词器、解析器）。

示例：references/patterns.md。