# Type ## Description Type 模块用于提供面向 TypeScript 类型系统（type system）的通用类型建模能力，主要承载类型判断、类型组合、类型转换以及类型结构重塑等公共语义。 它并不是为了堆叠炫技式的类型体操，而是为了沉淀一组能够长期复用、命名稳定、语义清楚的类型层工具。这个模块关注的是“哪些静态约束值得被抽象为基础模型”，而不是让局部实现里的技巧性写法直接变成公共 API。 ## For Understanding 理解 Type 模块时，应先区分它与运行时工具模块的职责差异。这里解决的问题发生在编译阶段：如何表达约束、如何描述结构关系、如何在类型层提前暴露不合法的使用方式、以及如何把一组复杂条件压缩成更稳定的公共类型语义。 因此，这个模块适合放在公共 API 设计、库封装、复杂配置建模、框架适配和类型推导增强等边界中。只要某个问题的核心是“能否在编译阶段更早发现错误”或“能否把约束用类型表达而不是运行时代码表达”，Type 模块通常就比继续增加运行时判断更合适。 也正因为如此，本模块的边界不应被理解为“所有和 TypeScript 有关的东西”。仅当一个能力表达的是稳定、可复用的类型语义时，它才适合进入这里。某个局部实现专用的类型补丁、只为绕过编译器局限而存在的临时技巧、或者过度依赖当前文件上下文的辅助类型，都不应轻易加入公共导出。 ## For Using 当你需要在静态层面表达类型关系，而不是在运行时反复写守卫与转换逻辑时，可以使用这个模块。它适合那些需要提高公共 API 可读性、约束复杂输入结构、维护类型推导结果稳定性、或在库层提供更强静态保证的场景。 从使用角度看，这个模块大致可以分为几类能力。第一类是基础判断与辅助能力，用于表达原始类型、对象、数组、函数、类等常见结构的静态条件。第二类是关系与运算能力，用于处理联合、交叉、字面量、路径等类型之间的组合与转换。第三类是结构重塑能力，用于在对象、数组、元组、函数签名等结构之间做映射、拆分、约束和重组。 更合理的使用方式，是先从你要表达的语义出发，再选取最接近该语义的类型工具，而不是把它们当作纯技巧库随意拼接。只要类型声明开始主要服务于“让编译器刚好不报错”，而不是帮助调用方理解边界，那通常意味着抽象方向已经偏离了这个模块的目标。 ## For Contributing 贡献 Type 模块时，应先回答两个问题：新增能力解决的是不是一个可长期复用的类型建模问题，以及它是否能以清楚、稳定、可读的形式向外承诺。只有在这两个问题的答案都足够明确时，一个新类型才值得被公开导出。 在实现层面，应优先保证语义清晰和调用方面向的可读性，再考虑技巧性。复杂递归、分布式条件类型、累加器模式或品牌类型等写法本身并不构成价值；真正的价值在于它们是否帮助调用方稳定地理解某个约束。若一个类型只是在内部为另一个公开类型服务，就应优先把它保留为内部辅助项，而不是公开成新的通用工具。 ### JSDoc 注释格式要求 - 每个公开导出的目标（类型、函数、变量、类等）都应包含 JSDoc 注释，让人在不跳转实现的情况下就能理解用途。 - JSDoc 注释第一行应为清晰且简洁的描述，该描述优先使用中文（英文也可以）。 - 如果描述后还有其他内容，应在描述后加一个空行。 - 如果有示例，应使用 `@example` 标签，后接三重反引号代码块（不带语言标识）。 - 如果有示例，应包含多个场景，展示不同用法，尤其要覆盖常见组合方式或边界输入。 - 如果有示例，应使用注释格式说明每个场景：`// Expect: `。 - 如果有示例，应将结果赋值给 `example1`、`example2` 之类的变量，以保持示例易读。 - 如果有示例，`// Expect: ` 应该位于 `example1`、`example2` 之前，以保持示例的逻辑清晰。 - 如果有示例，应优先使用确定性示例；避免断言精确的随机输出。 - 如果函数返回结构化字符串，应展示其预期格式特征。 - 如果有参考资料，应将 `@see` 放在 `@example` 代码块之后，并用一个空行分隔。 ### 实现规范要求 - 不同程序元素之间使用一个空行分隔，保持结构清楚。这里的程序元素，通常指函数、类型、常量，以及直接服务于它们的辅助元素。 - 某程序元素独占的辅助元素与该程序元素本身视为一个整体，不要在它们之间添加空行。 - 程序元素的辅助元素应该放置在该程序元素的上方，以保持阅读时的逻辑顺序。 - 若辅助元素被多个程序元素共享，则应将其视为独立的程序元素，放在这些程序元素中第一个相关目标的上方，并与后续程序元素之间保留一个空行。 - 辅助元素也应该像其它程序元素一样，保持清晰的命名和适当的注释，以便在需要阅读实现细节时能够快速理解它们的作用和使用方式。 - 辅助元素的命名必须以前缀 `internal` 开头（或 `Internal`，大小写不敏感）。 - 辅助元素永远不要公开导出。 - 被模块内多个不同文件中的程序元素共享的辅助元素，应该放在一个单独的文件中，例如 `./src/type/internal.ts`。 - 模块内可以包含子模块。只有当某个子目录表达一个稳定、可单独理解、且可能被父模块重导出的子问题域时，才应将其视为子模块。 - 子模块包含多个文件时，应该为其单独创建子文件夹，并为其创建单独的 Barrel 文件；父模块的 Barrel 文件再重导出子模块的 Barrel 文件。 - 子模块不需要有自己的 `README.md`。 - 子模块可以有自己的 `internal.ts` 文件，多个子模块共享的辅助元素应该放在父模块的 `internal.ts` 文件中，单个子模块共享的辅助元素应该放在该子模块的 `internal.ts` 文件中。 - 对模块依赖关系的要求（通常是不循环依赖或不反向依赖）与对 DRY 的要求可能产生冲突。此时，若复用的代码数量不大，可以适当牺牲 DRY，复制粘贴并保留必要的注释说明；若复用的代码数量较大，则可以将其抽象到新的文件或子模块中，如 `common.ts`，并在需要的地方导入使用。 - 对复杂条件类型、递归类型、累加器模式或分布式条件类型，应优先让公开 API 保持最小、清晰、稳定的参数面，而不要把内部技巧直接暴露给调用方。 ### 导出策略要求 - 保持内部辅助项和内部符号为私有，不要让外部接入依赖临时性的内部结构。 - 每个模块都应有一个用于重导出所有公共 API 的 Barrel 文件。 - Barrel 文件应命名为 `index.ts`，放在模块目录根部，并且所有公共 API 都应从该文件导出。 - 新增公共能力时，应优先检查它是否表达稳定、清楚且值得长期维护的类型语义，而不是某段实现细节的便捷暴露；仅在确认需要长期对外承诺时再加入 Barrel 导出。 ### 测试要求 - 若程序元素是函数，则只为该函数编写一个测试，如果该函数需要测试多个用例，应放在同一个测试中。 - 若程序元素是类，则至少要为该类的每一个方法编写一个测试，如果该方法需要测试多个用例，应放在同一个测试中。 - 若程序元素是类，除了为该类的每一个方法编写至少一个测试之外，还可以为该类编写任意多个测试，以覆盖该类的不同使用场景或边界情况。 - 若编写测试时需要用到辅助元素（Mock 或 Spy 等），可以在测试文件中直接定义这些辅助元素。若辅助元素较为简单，则可以直接放在每一个测试内部，优先保证每个测试的独立性，而不是追求极致 DRY；若辅助元素较为复杂或需要在多个测试中复用，则可以放在测试文件顶部，供该测试文件中的所有测试使用。 - 测试顺序应与源文件中被测试目标的原始顺序保持一致。 - 此模块暂时不需要任何测试，类型系统的测试通常需要特定的工具链支持，开发和维护成本较高，因此在没有明确需求的情况下，先保持模块的纯粹封装性质也是合理的。 - 模块的单元测试文件目录是 `./tests/unit/type`，若模块包含子模块，则子模块的单元测试文件目录为 `./tests/unit/type/`。