Valibot 中 transform 与类型推断的注意事项

Valibot 是一个强大的 TypeScript 数据验证库，它提供了丰富的模式验证功能。在使用过程中，开发者经常会遇到类型推断与模式转换的问题，特别是当使用 transform 方法时，类型系统需要特别注意。

问题背景

在 Valibot 中，transform 方法允许我们对验证后的值进行转换。例如，我们可以将 ISO 格式的日期字符串转换为 JavaScript 的 Date 对象。然而，这种转换在类型系统中需要明确区分输入类型和输出类型。

核心概念

Valibot 的 GenericSchema 类型接受两个泛型参数：

1. 第一个参数表示输入数据的类型
2. 第二个参数表示输出数据的类型

当只提供一个泛型参数时，Valibot 会假定输入和输出类型相同。这就是为什么在使用 transform 时会出现类型不匹配的问题。

正确用法

对于需要类型转换的场景，我们应该明确指定输入和输出类型：

// 定义输入和输出类型
type Input = { date: string };
type Output = { date: Date };

// 创建转换管道
const IsoDate = v.pipe(
  v.string(),
  v.isoTimestamp(),
  v.transform((dateStr) => new Date(dateStr))
);

// 创建模式并验证类型
const Schema = v.strictObject({
  date: IsoDate,
}) satisfies v.GenericSchema<Input, Output>;

类型系统解析

1. 输入类型：string（来自 v.string()）
2. 中间验证：v.isoTimestamp() 确保字符串是有效的 ISO 时间戳
3. 输出类型：Date（来自 transform 转换）

如果不明确区分输入和输出类型，TypeScript 会认为整个模式的输入和输出类型应该一致，从而导致类型错误。

最佳实践

1. 当使用 transform 时，总是考虑输入和输出类型的差异
2. 为复杂转换定义明确的输入和输出类型
3. 使用 satisfies 进行类型检查，确保模式定义与预期类型一致
4. 对于不涉及类型转换的简单验证，可以省略第二个泛型参数

总结

Valibot 的类型系统设计得非常精确，能够很好地处理数据验证和转换场景。理解输入和输出类型的区别是正确使用 transform 方法的关键。通过明确指定这两个类型参数，我们可以构建既安全又灵活的数据验证流程，同时享受 TypeScript 强大的类型检查带来的好处。