typescript-advanced-patterns

TypeScript 高级模式最佳实践

超越 TypeScript 5.x 表层用法的类型级编程、库作者惯用写法和功能实现模式。包含 5 个类别中的 40 条规则，按对使用者代码库的影响排序。

何时应用

在以下情况下参考这些指南：

• 设计公共库或 DSL 接口（流式构建器、事件发射器、路由解析器、查询构建器、由模式派生的客户端）
• 编写类型级算法（递归条件类型、累加器模式、键重映射、可变元组、类型级字符串／数字运算、类型级测试）
• 以非简单方式使用 TS 5.x 功能（Stage 3 装饰器、using 组合、用于重载消歧的 const T、用于区分锚定参数与受约束参数的 NoInfer、方差注解、双变漏洞）
• 在类型层面编码工作流状态、转换和能力，使非法状态和缺少的检查成为编译错误
• 与声明和模块系统集成（模块扩充、声明合并、环境资源模块、通过 exports／typesVersions 发布库类型）

与相邻技能的边界

技能	以下需求不适用此技能……
typescript（精选）	编译器性能／tsconfig 调优
typescript-refactor	通用重构模式和现代 TS 基础用法
ts-google	Google 风格的代码风格决策
clean-code-ts-react	整洁代码原则（命名、函数形态、抽象）
effect-ts／opencode-ts	Effect 库特定模式

如果此技能中的规则与 typescript-refactor 或 .curated/typescript 中的规则重叠，该规则的 适用范围差异 部分会说明此技能在基础版本之上新增的内容。

按优先级排列的规则类别

优先级	类别	影响	前缀	规则数
1	库作者／DSL 模式	严重	dsl-	8
2	类型级编程	高	tlp-	10
3	深入使用现代功能	高	mod-	8
4	功能实现模式	中高	impl-	8
5	声明和模块系统	中	decl-	6

快速参考

1. 库作者／DSL 模式（严重）

• dsl-fluent-builder-phantom-state — 使用虚设状态类型强制执行构建器调用顺序
• dsl-typed-event-emitter — 使用映射事件映射构建类型化事件发射器
• dsl-type-safe-object-paths — 使用点表示法推断对象路径访问类型
• dsl-route-param-inference — 从路径模式推断路由参数
• dsl-schema-first-inference — 从运行时模式派生静态类型
• dsl-type-safe-query-builder — 在构建器的返回类型中编码查询形状
• dsl-narrow-api-surface — 仅导出 API 接口，而非内部辅助项
• dsl-overloads-vs-conditional-returns — 选择重载而非条件返回类型

2. 类型级编程（HIGH）

• tlp-recursive-conditional-types — 使用递归条件类型执行结构转换
• tlp-tail-recursion-accumulator — 使用尾递归累加器模式绕过 50 步限制
• tlp-infer-extends-constraints — 使用 extends 约束 infer，以进行经过验证的提取
• tlp-key-remapping-as — 在映射类型中使用 as 子句重新映射键
• tlp-variadic-tuple-types — 使用可变元组编写感知位置的类型算法
• tlp-type-level-string-algorithms — 使用递归模板字面量构建类型级字符串算法
• tlp-distributive-conditional-control — 使用 [T] extends [U] 元组技巧控制分配
• tlp-type-level-tests — 使用 Equal、Expect 和 @ts-expect-error 测试类型
• tlp-template-literal-pattern-matching — 使用模板字面量中的 infer 匹配结构化字符串
• tlp-hkt-emulation — 使用接口字典模拟高阶类型

3. 深入掌握现代特性（HIGH）

• mod-stage-3-decorators — 使用带有装饰器上下文的 Stage 3 装饰器进行元编程
• mod-using-disposal-ordering — 组合 using 资源并显式指定释放顺序
• mod-const-type-params-overloads — 使用 const T 在重载 API 中保留字面量类型
• mod-noinfer-overload-disambiguation — 使用 NoInfer<T> 消除重载函数签名的歧义
• mod-variance-debugging — 使用 in/out 注解调试变型错误
• mod-method-vs-property-bivariance — 优先使用属性语法而非方法语法，以避免双变性漏洞
• mod-phantom-capability-tracking — 使用幽灵标记在类型级别跟踪能力
• mod-satisfies-branded-config — 将 satisfies 与品牌类型结合，用于验证配置

4. 特性实现模式（MEDIUM-HIGH）

• impl-tagged-result-type — 将操作结果建模为 Ok<T> | Err<E> 标记联合类型
• impl-state-discriminated-union — 将工作流状态建模为状态记录的可辨识联合类型
• impl-finite-state-machine — 在函数签名中编码有限状态机（FSM）转换
• impl-schema-derived-api-client — 从端点架构推导客户端参数和返回值类型
• impl-type-safe-form-builder — 根据单一架构定义推导表单字段类型
• impl-phantom-feature-flags — 使用幽灵能力类型控制依赖特性的代码
• impl-assert-never-exhaustive — 使用 assertNever 强制穷尽处理联合类型的所有变体
• impl-env-config-loader — 在边界处通过架构推导验证环境配置

5. 声明与模块系统（中等）

• decl-module-augmentation — 无需修改源代码即可扩展第三方模块类型
• decl-declaration-merging — 合并接口、命名空间和类声明以扩展 API
• decl-ambient-asset-modules — 为非 TypeScript 资源导入声明环境模块
• decl-global-augmentation-discipline — 限定全局类型扩展的作用域，以避免冲突
• decl-exports-and-types-versions — 使用 exports 和 typesVersions 映射发布库类型
• decl-authoring-d-ts-for-js — 为纯 JavaScript 库编写 .d.ts 文件

使用方法

阅读各个参考文件，了解详细说明、代码示例以及“何时不应采用”的指导：

• 章节定义 — 类别结构和影响级别
• 规则模板 — 添加新规则的模板

规则通过 [[other-rule-slug]] 互相链接；遇到相关模式时，请参阅链接的规则。

参考文件

文件	描述
references/_sections.md	类别定义和排序
assets/templates/_template.md	新规则模板
metadata.json	版本和参考信息