Valibot 中函数类型验证的思考与实践

在 TypeScript 生态中，Valibot 作为一个数据验证库，其类型安全特性受到了开发者们的广泛关注。本文将探讨 Valibot 中函数类型验证的实现方式及其背后的设计哲学。

函数类型验证的需求场景

在实际开发中，我们经常需要验证回调函数的类型。例如，一个计时器组件可能接受包含 onProgress 和 onComplete 回调的配置对象：

const timerOptions = {
  onProgress: (progress: number) => void,
  onComplete: () => void
}

开发者期望能够对这些回调函数的类型进行验证，确保传入的函数参数符合预期。

直接泛型化的局限性

初看之下，为 Valibot 的 function_ 方法添加泛型参数似乎是个不错的解决方案：

v.function<(progress: number) => void>()

然而，这种方法存在根本性问题：它只能提供编译时的类型提示，而无法在运行时验证函数参数的实际类型。TypeScript 的类型系统会在编译时被擦除，导致运行时无法获取函数的参数类型信息。

类型安全与运行时验证的平衡

Valibot 的设计哲学强调真正的运行时验证。单纯的类型提示无法保证：

1. 函数参数的实际类型
2. 函数参数的个数
3. 函数的返回值类型

如果仅依赖类型系统，当用户直接使用 JavaScript 编写代码时，这些验证将完全失效。

实践解决方案

对于需要精确函数类型验证的场景，Valibot 推荐使用 custom 验证器：

const progressValidator = v.custom<(progress: number) => void>(
  (value) => typeof value === 'function'
)

开发者可以在此基础上添加更详细的运行时验证逻辑，例如：

const strictProgressValidator = v.custom<(progress: number) => void>(
  (value) => {
    if (typeof value !== 'function') return false
    try {
      value(0) // 测试传入数字参数
      value('test') // 测试错误参数类型（应抛出错误）
      return false
    } catch {
      return true
    }
  }
)

设计取舍的思考

Valibot 选择不直接提供泛型化的函数验证器，体现了几个重要的设计决策：

1. 运行时安全优先：宁可缺少类型便利，也要保证运行时行为正确
2. 明确职责划分：将复杂场景交给 custom 验证器处理
3. 避免误导性安全：防止开发者误以为类型提示等同于运行时验证

实际应用建议

对于大多数场景，可以结合使用：

1. 基础函数验证：v.function()
2. JSDoc 类型提示：通过注释提供开发体验
3. 关键路径：使用 custom 进行严格验证

/**
 * @type {import('valibot').Schema<(progress: number) => void>}
 */
const progressSchema = v.function()

这种组合方式既保持了运行时安全性，又提供了良好的开发体验。

总结

Valibot 在函数类型验证上的设计体现了其对运行时安全性的坚持。理解这一设计哲学，开发者可以更合理地构建自己的验证逻辑，在类型安全和运行时验证之间取得平衡。对于需要精确函数验证的场景，custom 验证器提供了足够的灵活性和控制力。