Valibot 中 nonOptional 与转换器组合时的边界情况解析

Valibot 是一个优秀的 TypeScript 数据验证库，以其出色的组合性和可扩展性著称。在使用过程中，开发者可能会遇到一个关于 nonOptional 与转换器组合时的边界情况，本文将深入分析这一问题的本质及其解决方案。

问题现象

当开发者尝试构建一个基础字符串类型，将空字符串转换为 undefined 时，可能会编写如下代码：

const String = v.nonOptional(
  v.pipe(
    v.string(),
    v.transform((val) => val?.trim() || undefined),
  ),
);

然后在此基础上添加长度验证：

const Password = v.pipe(String, v.minLength(6))

当解析空字符串时，尽管使用了 safeParse，代码仍会抛出运行时错误，提示无法读取 undefined 的 length 属性。

问题根源

这一问题的核心在于 nonOptional 的设计行为：

1. 输入输出检查差异：nonOptional 仅检查输入值是否为 undefined，而不检查转换后的输出值
2. 类型系统局限性：TypeScript 无法在编译时推断转换函数内部逻辑，导致类型系统与实际运行时行为不一致
3. 管道处理顺序：转换器在 nonOptional 之后执行，导致 nonOptional 无法感知最终的输出值

解决方案分析

Valibot 团队考虑了多种解决方案：

1. 移除相关功能：显然过于极端，影响用户体验
2. 限制使用方式：禁止在管道中使用，但会限制库的灵活性
3. 保留类型缺陷：仅作为已知问题记录，但对企业级应用不够友好
4. 增强输出检查：让 nonOptional 同时检查输入和输出

最终，Valibot 选择了最合理的第4种方案，在 v1.0.0-beta.5 版本中修复了这一问题。

最佳实践建议

1. 明确检查边界：对于需要确保非空的场景，建议显式添加输出检查

   const NonOptionalOutput = v.pipe(
     OptionalOutput,
     v.check((input) => input !== undefined),
   );
   

2. 理解默认值行为：optional 的第二个参数是默认输入值而非回退输出值，对于回退场景应使用 fallback

3. 组合使用验证：对于复杂的验证逻辑，建议分层组合简单验证器，而非单一复杂管道

设计哲学启示

这一问题的解决体现了 Valibot 的几个核心设计理念：

1. 渐进式严格：在保证主要用例流畅的同时，逐步完善边界情况
2. 开发者体验优先：即使需要付出额外实现成本，也要确保直观的开发者体验
3. 类型安全至上：不因运行时便利而牺牲类型系统的准确性

总结

Valibot 通过这一修复，进一步巩固了其作为 TypeScript 验证库领导者的地位。开发者在使用时应当理解验证器的输入输出边界，合理组合各种验证操作，以构建健壮且类型安全的验证逻辑。对于企业级应用，建议建立内部验证器库，封装这类边界情况的处理，确保团队一致性。