Runtypes v7.0.0 重大版本升级解析

Runtypes 是一个强大的 TypeScript 运行时类型检查库，它允许开发者在运行时验证数据结构的类型安全性。这个库特别适合在需要同时保证编译时类型安全和运行时数据验证的场景中使用，比如 API 请求/响应验证、配置验证等。

版本升级概览

Runtypes v7.0.0 是一个重大版本更新，带来了多项突破性变更和功能增强。这个版本对核心架构进行了重构，优化了类型推断性能，并引入了多项新特性，使库更加健壮和易用。

主要变更内容

1. 核心类型重命名

为了更准确地表达语义，v7 对几个核心类型进行了重命名：

• Record 重命名为 Object，更符合 JavaScript 的术语习惯
• Dictionary 重命名为 Record，同时调整了参数顺序为 Record(Key, Value)
• 工具方法 .Or() 和 .And() 改为小写形式 .or() 和 .and()

2. Optional 语义变更

Optional 不再是独立的运行时类型，而是仅作为 Object 字段的上下文包装器。这一变更使得类型系统更加精确，特别是与 TypeScript 的 noUncheckedIndexedAccess 标志配合使用时。

3. 验证方法重构

.validate() 方法被重命名为 .inspect()，并且默认执行解析操作。这一变更使得 API 更加直观，因为检查(inspect)通常隐含了解析的含义。

4. 错误处理改进

Failure 的结构进行了重大调整，现在包含了验证失败的完整细节信息。这使得错误调试更加方便，开发者可以清晰地看到每个验证步骤的失败原因。

重要新特性

1. 解析功能

v7 引入了强大的解析功能，可以在验证后对数据进行转换。例如：

const PositiveNumber = Number.withConstraint(n => n > 0).withParser(Math.floor);

2. 精确对象验证

新增了对精确对象验证的支持，可以确保对象不包含未声明的额外属性：

const ExactPerson = Object({
  name: String,
  age: Number
}).asExact();

3. 变长元组支持

现在可以方便地定义变长元组类型：

const VariadicTuple = Tuple(String, Number).withRest(Boolean);

4. 类型适配辅助方法

新增了 .conform() 辅助方法，可以方便地将运行类型适配到预定义的静态类型：

interface Person {
  name: string;
  age: number;
}

const PersonRuntype = Object({
  name: String,
  age: Number
}).conform<Person>();

5. 对象属性扩展

提供了便捷的方法来扩展对象类型的属性：

const Base = Object({ x: Number });
const Extended = Base.with({ y: String });  // 现在有 x 和 y 两个属性

性能优化

v7 版本对类型系统进行了多项性能优化：

• 减少了 Union 和 Intersect 类型的计算成本
• 优化了 Static 类型的推断性能
• 改进了递归对象类型的处理效率

开发者体验改进

• 错误消息更加清晰和详细
• 改进了对 Symbol 类型值的处理
• 提供了更精确的类型提示
• 增强了 API 的一致性

迁移建议

对于从 v6 迁移到 v7 的项目，建议：

1. 首先更新所有重命名的类型和方法
2. 检查所有使用 Optional 的地方，确保它们仅用于对象字段
3. 将 .validate() 调用替换为 .inspect()
4. 利用新的解析功能重构现有的数据转换逻辑
5. 考虑使用新的精确对象验证来加强数据完整性检查

Runtypes v7.0.0 的这些改进使得它在类型安全和运行时验证方面更加强大和易用，是 TypeScript 项目中处理复杂数据验证的理想选择。