TanStack Form 中处理 Zod 品牌类型的正确方式

在 TypeScript 开发中，我们经常使用 Zod 这样的类型安全验证库来定义数据结构。Zod 提供了品牌类型(branded types)的功能，允许开发者创建名义类型(nominal typing)，这在 TypeScript 的结构化类型系统中非常有用。然而，当我们将 Zod 与 TanStack Form 结合使用时，可能会遇到品牌类型处理不当的问题。

问题现象

当开发者使用 Zod 定义包含品牌类型的表单结构时，例如：

const schema = z.object({
  id: z.string().brand<'Id'>()
})

期望表单能够正确推断出 id 字段应该是 string & { __brand: "Id" } 类型，但实际上 TanStack Form 会将其推断为普通的 string 类型，丢失了品牌类型信息。

问题根源

这个问题实际上涉及两个层面的理解：

1. Zod 的类型系统：Zod 有输入类型(input)和输出类型(output)的概念。品牌类型属于输出类型，因为它是在验证过程中添加的额外类型信息。

2. 表单库的预期行为：表单处理的是用户输入的数据，这些数据在提交前尚未经过 Zod 的完整验证和转换，因此应该使用输入类型而非输出类型。

解决方案

正确的做法是区分表单的输入类型和验证后的输出类型：

1. 定义品牌类型：

const vehicleIdSchema = z.string().brand<'ID'>();
type VehicleId = z.output<typeof vehicleIdSchema>; // 验证后的类型

2. 在表单中使用输入类型：

const form = useForm({
  defaultValues: {
    id: '12313-1231' // 这里使用普通字符串
  },
  validators: {
    onChange: zodSchema // 验证时会转换为品牌类型
  }
});

3. 在提交处理中使用输出类型：

onSubmit: async ({ value }) => {
  // value.id 现在是 VehicleId 类型
}

深入理解

品牌类型在运行时并不存在，它们纯粹是 TypeScript 的类型系统特性。Zod 的品牌类型功能允许我们在类型层面区分看似相同但实际上语义不同的字符串，例如用户ID和订单ID可能都是字符串，但在业务逻辑中不应混用。

TanStack Form 的设计哲学是：

• 表单处理的是原始输入数据
• 验证器负责转换和验证这些数据
• 提交时获得的是经过验证和转换的数据

这种分离确保了类型安全同时不牺牲开发体验。

最佳实践

1. 对于表单的 defaultValues，使用输入类型
2. 在验证器中使用完整的 Zod 模式(包含品牌类型)
3. 在提交处理器中，可以安全地假设数据已经过验证并具有品牌类型
4. 考虑为常用品牌类型创建类型别名，提高代码可读性

通过这种方式，开发者既能享受品牌类型带来的类型安全优势，又能与 TanStack Form 无缝集成。