用途:TanStack DB 使用 schema 在数据变更(insert/update)时校验并转换数据。schema 可选,但为类型安全与数据完整性推荐使用。兼容任何 StandardSchema 库:Zod、Valibot、ArkType、Effect Schema。
主要能力:基础校验在 createCollection 的 queryCollectionOptions 中传入 schema,非法数据抛出 SchemaValidationError。支持默认值(如 z.boolean().default(false)、z.date().default(() => new Date())),插入时自动填充。支持类型转换:用 z.union([A, B]).transform(...) 将输入类型转为输出类型。校验模式包含字符串约束、数字约束、枚举、optional/nullable、数组、refine 自定义校验、跨字段校验。也支持计算字段(在 transform 中派生 final_price 等)。
使用方式:在集合选项中声明 schema,例如 createCollection(queryCollectionOptions({ schema: todoSchema, queryKey: ['todos'], queryFn: async () => api.todos.getAll(), getKey: (item) => item.id }))。捕获错误用 try/catch 判断 instanceof SchemaValidationError,读取 error.type、error.message、error.issues(含 path、message),可映射到 React 表单错误状态。
关键限制:TInput 必须是 TOutput 的超集,否则 update 会失败;若转换 A→B,输入应写 z.union([A, B])。schema 只校验客户端变更,不校验服务端数据;TypeScript 类型自动推断,提供 schema 后不要再传显式类型参数;转换会同步运行于每次变更,需保持简单。handlers 接收的是 TOutput(转换在 handler 之前执行),若 API 需其他格式需在 handler 内序列化。
适用场景:为 TanStack DB 集合添加类型安全、默认值与字段转换,尤其表单提交与跨字段校验。资料未提供安装命令、收费与价格信息。