Valibot 中处理表单输入类型的扩展方案解析

背景介绍

Valibot 是一个强大的 TypeScript 数据验证库，它提供了严格的类型安全机制来确保数据符合预期格式。在实际开发中，特别是在构建表单时，我们经常会遇到需要处理"可接受的无效输入"的情况。这类输入虽然不符合最终验证要求，但在表单交互过程中有其特殊意义。

问题场景

以 React + MUI 或 MUI Joy 等前端框架为例，表单控件经常会使用特定值来表示"空值"状态，例如：

• null 表示未选择状态
• 空字符串 '' 表示文本输入框未填写

这些值虽然不符合业务数据的最终要求，但在表单状态管理中却有着重要作用。开发者需要：

1. 确保表单初始状态正确设置这些特殊值
2. 在表单逻辑中明确处理这些特殊状态
3. 同时保持最终验证数据的纯净性

技术挑战

Valibot 的核心设计是确保输入数据严格符合预期，但表单交互过程需要更灵活的类型处理。主要挑战包括：

1. 如何扩展输入类型而不影响输出类型
2. 保持类型系统的完整性
3. 提供直观的开发者体验

解决方案探索

最初提出的方案是使用 input 泛型方法：

const RepeatSchema = v.input<null>(v.picklist(['daily', 'weekly', 'monthly']));

这种方法虽然直观，但在 TypeScript 实现上遇到了技术限制——无法只指定部分泛型参数。

经过深入探讨，提出了几种替代方案：

1. 函数柯里化方案：创建返回函数的工厂方法
2. 组合验证方案：利用现有的管道验证机制

最终推荐方案

Valibot 团队最终推荐使用 pipe 函数组合验证器的方式：

const Schema1 = v.picklist(['foo', 'bar']);
const Schema2 = v.pipe(v.nullable(Schema1), Schema1);

这种方案的优势在于：

• 完全利用现有 API，无需新增概念
• 输入类型自动包含 null，输出类型保持纯净
• 类型推断完全符合预期
• 可组合性强，适用于复杂场景

类型系统解析

让我们深入理解这种方案的类型行为：

1. v.nullable(Schema1)：创建一个接受 'foo' | 'bar' | null 的验证器
2. v.pipe(..., Schema1)：先应用可空验证，再应用严格验证
   • 输入类型：保留可空验证的输入类型
   • 输出类型：使用最终验证器的输出类型

这种设计完美实现了：

• 开发时：能明确处理 null 情况
• 运行时：确保最终数据不包含 null

实际应用示例

在 React 表单中的典型应用：

// 定义表单模型
const FormSchema = v.object({
  username: v.pipe(v.nullable(v.string()), v.string()),
  repeat: v.pipe(v.nullable(v.picklist(['daily', 'weekly'])), v.picklist(['daily', 'weekly']))
});

// 初始状态
const [form, setForm] = useState<v.InferInput<typeof FormSchema>>({
  username: null,
  repeat: null
});

// 提交处理
const handleSubmit = () => {
  const result = v.safeParse(FormSchema, form);
  if (result.success) {
    // result.data 类型已自动排除 null
    submitToServer(result.data);
  }
};

最佳实践建议

1. 明确区分输入输出类型：始终使用 InferInput 和 InferOutput 获取正确类型
2. 表单状态初始化：使用输入类型定义初始状态
3. 业务逻辑处理：使用输出类型处理验证后的数据
4. 复杂结构处理：对于嵌套对象，可以在适当层级应用此模式

总结

Valibot 通过巧妙的验证器组合方式，既保持了核心验证逻辑的严格性，又为表单交互等场景提供了必要的灵活性。这种设计体现了几个重要原则：

1. 类型系统的精确性与实用性的平衡
2. 最小 API 表面与最大表达能力的结合
3. 对常见开发场景的深入理解

开发者可以放心使用这种模式构建类型安全且用户体验良好的表单系统，而无需担心类型系统与运行时行为的不一致。