Valibot 0.38.0 版本中 transform 与 pipe 的兼容性问题解析

Valibot 是一个用于数据验证的 TypeScript 库，在 0.38.0 版本中引入了一个关于 transform 和 pipe 组合使用的重大变更。这个变更影响了某些特定场景下的类型推断行为，本文将深入分析这一变更的技术背景、影响范围以及解决方案。

问题本质

在 Valibot 0.38.0 之前，开发者可以自由地在 pipe 中使用 transform 将输入值转换为任意类型，包括 undefined。然而，从 0.38.0 版本开始，这种模式在某些情况下会引发类型错误。

核心问题出现在当 transform 返回一个可能为 undefined 的值，而后续的验证器期望一个确定类型的输入时。例如：

v.pipe(
  v.string(),
  v.transform((x) => x === 'foo' ? 123 : undefined), // 可能返回 undefined
  v.integer(), // 期望输入必须是 number
);

这种模式在 0.37.0 版本中可以正常工作，但在 0.38.0 中被视为类型错误。

设计意图

Valibot 维护者明确指出，这一变更是有意为之的。0.37.0 及之前版本的行为实际上是一个 bug。新的类型系统强制要求管道中的每个验证器必须能够处理前一个验证器的输出类型。

这种设计背后的理念是：

1. 确保类型安全，防止无效的验证链
2. 强制开发者显式处理所有可能的输出情况
3. 保持验证逻辑的清晰性和可预测性

实际应用场景

在实际开发中，这种模式常见于需要将字符串转换为数字的场景。例如，验证端口号的典型实现：

function toNumber(string: string): number | undefined {
  if (/[^\d\s+.E-]/iu.test(string)) return undefined;
  const number = Number(string);
  if (!Number.isFinite(number)) return undefined;
  return number;
}

const PORT_SCHEMA = v.optional(
  v.pipe(
    v.string(),
    v.transform((x) => toNumber(x)),
    v.integer(),
    v.minValue(0),
    v.maxValue(65_535),
  ),
);

在 0.38.0 中，这种写法会引发类型错误，因为 integer() 验证器无法处理 undefined 输入。

解决方案

针对这一问题，Valibot 提供了几种解决方案：

1. 前置验证法

在转换前先验证输入是否符合数字格式：

const PORT_SCHEMA = v.optional(
  v.pipe(
    v.string(),
    v.check(
      (x) => !/[^\d\s+.E-]/iu.test(x) && Number.isFinite(Number(x)),
      "必须为有效数字"
    ),
    v.transform(Number),
    v.integer(),
    v.minValue(0),
    v.maxValue(65_535),
  ),
);

2. 正则表达式验证法

使用正则表达式预先过滤无效输入：

const PORT_SCHEMA = v.optional(
  v.pipe(
    v.string(),
    v.regex(/[^\d\s+.E-]/iu),
    v.transform(Number),
    v.finite(),
    v.integer(),
    v.minValue(0),
    v.maxValue(65_535),
  ),
);

3. 类型断言法（临时方案）

作为过渡方案，可以使用类型断言：

v.integer() as v.BaseValidation<
  number | undefined,
  number,
  v.IntegerIssue<number>
>

未来发展方向

Valibot 维护者正在考虑在未来的版本中放宽类型限制，允许更灵活的管道组合。可能的解决方案包括：

1. 将管道中的输入类型检查改为 unknown，使任何验证器都可以接受前一个验证器的输出
2. 引入更精细的类型系统，区分验证器的输入要求和输出保证

最佳实践建议

基于当前版本的限制，建议开发者：

1. 尽量在转换前完成输入验证，确保转换函数总是返回预期类型
2. 避免在转换函数中返回混合类型（如 number | undefined）
3. 对于复杂的转换逻辑，考虑拆分为多个验证步骤
4. 关注 Valibot 的更新，及时调整验证策略

通过理解这些变更背后的设计理念和采用适当的解决方案，开发者可以继续利用 Valibot 构建健壮的数据验证逻辑。