Valibot 中 optional 与 undefinedable 的类型安全问题解析

Valibot 是一个 TypeScript 数据验证库，最近在其 beta 版本中关于 optional 和 undefinedable 的类型定义与运行时行为不一致的问题引发了开发者社区的讨论。本文将深入分析这一问题的技术背景、影响范围以及可能的解决方案。

问题本质

Valibot 目前存在类型定义与运行时行为不匹配的情况：

1. optional 类型定义为 { field?: number }，但运行时接受 { field: undefined }
2. undefinedable 类型定义为 { field: number | undefined }，但运行时也接受 {}
3. unknown 类型定义为 { field: unknown }，但运行时同样接受 {}

这种不一致在使用 TypeScript 的 exactOptionalPropertyTypes 严格模式时会导致类型安全问题，使类型系统无法正确推断属性是否存在。

技术影响

当启用 exactOptionalPropertyTypes 时，TypeScript 会严格区分以下三种情况：

1. 必须存在的属性：{ field: number }
2. 可选但存在时必须非 undefined 的属性：{ field?: number }
3. 显式允许 undefined 的属性：{ field: number | undefined }

Valibot 当前的运行时行为实际上相当于把所有情况都视为第三种，但类型定义却声称是前两种，这会导致：

• 类型守卫失效：if ("field" in obj) 的判断不可靠
• 类型窄化错误：可能将 undefined 误认为其他类型
• 类型转换问题：可能绕过类型系统进行不安全的类型转换

解决方案探讨

社区提出了几种可能的解决方向：

1. 调整类型定义：使类型定义匹配运行时行为，将所有可选属性都声明为 { field?: number | undefined }。这是 Zod 目前采用的方案，保持了类型安全但牺牲了一些类型精确度。

2. 调整运行时行为：使运行时行为匹配类型定义，严格区分缺失属性和 undefined 值。这会增加约 25% 的包体积，但提供更精确的类型检查。

3. 配置开关：引入全局配置选项，让用户选择是否启用 exactOptionalPropertyTypes 的严格模式。这增加了灵活性但也增加了复杂性。

4. 显式组合：鼓励用户手动组合 v.optional(v.undefinedable(...)) 来明确意图，但这将使用体验负担转嫁给用户。

最佳实践建议

在 Valibot 正式解决这一问题前，开发者可以采取以下措施保证类型安全：

1. 对于需要精确控制 undefined 行为的场景，显式使用组合验证：

v.object({
  strictOptional: v.optional(v.string()),
  looseOptional: v.optional(v.union([v.string(), v.undefined()]) 
})

2. 在关键类型转换处添加额外的运行时检查，不依赖单一的类型守卫。

3. 考虑在项目级别统一处理 optional 属性的策略，保持一致性。

未来展望

类型系统与运行时验证的一致性问题是所有验证库都需要面对的挑战。Valibot 团队正在积极评估各种方案，力求在类型安全、包体积和开发者体验之间找到最佳平衡点。随着 TypeScript 类型系统的发展，这一问题有望得到更优雅的解决方案。