zodix

zodix

优化Remix应用中的数据处理和验证流程

Zodix是一款为Remix应用优化的Zod工具集,专注于简化FormData和URLSearchParams的处理流程。该工具提供简洁API和自定义Zod模式,有效减少loader和action中的代码量,同时增强类型安全。Zodix适配多种Remix运行环境,具备完整的单元测试覆盖。其轻量化设计(gzip压缩后小于1KB)和零外部依赖的特性,使其成为Remix项目中高效的数据处理工具。

ZodixZodRemix表单验证数据解析Github开源项目

Zodix

构建状态 npm版本

Zodix是一个为Remix加载器和动作设计的Zod实用工具集合。它抽象了解析和验证FormDataURLSearchParams的复杂性,使您的加载器/动作保持简洁并具有强类型。

Remix加载器通常看起来像这样:

export async function loader({ params, request }: LoaderArgs) { const { id } = params; const url = new URL(request.url); const count = url.searchParams.get('count') || '10'; if (typeof id !== 'string') { throw new Error('id必须是字符串'); } const countNumber = parseInt(count, 10); if (isNaN(countNumber)) { throw new Error('count必须是数字'); } // 使用id和countNumber获取数据 };

使用Zodix后,同样的加载器如下所示:

export async function loader({ params, request }: LoaderArgs) { const { id } = zx.parseParams(params, { id: z.string() }); const { count } = zx.parseQuery(request, { count: zx.NumAsString }); // 使用id和countNumber获取数据 };

查看示例应用以获取常见模式的完整示例。

亮点

  • 显著减少Remix动作/加载器的冗余代码
  • 避免FormData和URLSearchParams的奇怪之处
  • 体积小,无外部依赖(gzip压缩后小于1kb
  • 使用现有的Zod模式,或即时编写
  • 为字符串化的数字、布尔值和复选框提供自定义Zod模式
  • 默认抛出适用于Remix CatchBoundary的错误
  • 支持非抛出式解析,用于自定义验证/错误
  • 适用于所有Remix运行时(Node、Deno、Vercel、Cloudflare等)
  • 完整的单元测试覆盖

设置

使用npm、yarn、pnpm等安装。

npm install zodix zod

导入zx对象或特定函数:

import { zx } from 'zodix'; // import { parseParams, NumAsString } from 'zodix';

使用方法

zx.parseParams(params: Params, schema: Schema)

使用Zod形状解析和验证来自LoaderArgs['params']ActionArgs['params']Params对象:

export async function loader({ params }: LoaderArgs) { const { userId, noteId } = zx.parseParams(params, { userId: z.string(), noteId: z.string(), }); };

与上面相同,但使用现有的Zod对象模式:

// 如果您有多个页面共享相同的参数,可以这样做。 export const ParamsSchema = z.object({ userId: z.string(), noteId: z.string() }); export async function loader({ params }: LoaderArgs) { const { userId, noteId } = zx.parseParams(params, ParamsSchema); };

zx.parseForm(request: Request, schema: Schema)

在Remix动作中解析和验证来自RequestFormData,避免繁琐的FormData操作:

export async function action({ request }: ActionArgs) { const { email, password, saveSession } = await zx.parseForm(request, { email: z.string().email(), password: z.string().min(6), saveSession: zx.CheckboxAsString, }); };

与现有的Zod模式和模型/控制器集成:

// db.ts export const CreateNoteSchema = z.object({ userId: z.string(), title: z.string(), category: NoteCategorySchema.optional(), }); export function createNote(note: z.infer<typeof CreateNoteSchema>) {}
import { CreateNoteSchema, createNote } from './db'; export async function action({ request }: ActionArgs) { const formData = await zx.parseForm(request, CreateNoteSchema); createNote(formData); // 这里没有TypeScript错误 };

zx.parseQuery(request: Request, schema: Schema)

解析和验证Request的查询字符串(搜索参数):

export async function loader({ request }: LoaderArgs) { const { count, page } = zx.parseQuery(request, { // NumAsString解析字符串数字("5")并返回数字(5) count: zx.NumAsString, page: zx.NumAsString, }); };

zx.parseParamsSafe() / zx.parseFormSafe() / zx.parseQuerySafe()

这些函数的工作方式与非安全版本相同,但在验证失败时不会抛出错误。它们使用z.parseSafe(),始终返回包含解析数据或错误的对象。

export async function action(args: ActionArgs) { const results = await zx.parseFormSafe(args.request, { email: z.string().email({ message: "无效的电子邮件" }), password: z.string().min(8, { message: "密码至少需要8个字符" }), }); return json({ success: results.success, error: results.error, }); }

查看登录页面示例以获取完整示例。

错误处理

parseParams()parseForm()parseQuery()

这些函数在解析失败时会抛出 400 响应。这与 Remix 捕获边界 配合使用效果很好,应该用于解析那些很少失败且不需要自定义错误处理的内容。您可以传递自定义错误消息或状态码。

export async function loader({ params }: LoaderArgs) { const { postId } = zx.parseParams( params, { postId: zx.NumAsString }, { message: "无效的 postId 参数", status: 400 } ); const post = await getPost(postId); return { post }; } export function CatchBoundary() { const caught = useCatch(); return <h1>捕获到错误:{caught.statusText}</h1>; }

查看 帖子页面示例 以获取完整示例。

parseParamsSafe()parseFormSafe()parseQuerySafe()

这些函数非常适合表单验证,因为它们在解析失败时不会抛出错误。它们总是返回一个具有以下结构的对象:

{ success: boolean; error?: ZodError; data?: <解析后的数据>; }

然后您可以在 action 中处理错误,并在组件中使用 useActionData() 访问它们。查看 登录页面示例 以获取完整示例。

辅助 Zod 模式

由于 FormDataURLSearchParams 将所有值序列化为字符串,您经常会遇到像 "5""on""true" 这样的情况。辅助模式处理解析和验证表示其他数据类型的字符串,旨在与解析函数一起使用。

可用的辅助函数

zx.BoolAsString

  • "true"true
  • "false"false
  • "notboolean" → 抛出 ZodError

zx.CheckboxAsString

  • "on"true
  • undefinedfalse
  • "anythingbuton" → 抛出 ZodError

zx.IntAsString

  • "3"3
  • "3.14" → 抛出 ZodError
  • "notanumber" → 抛出 ZodError

zx.NumAsString

  • "3"3
  • "3.14"3.14
  • "notanumber" → 抛出 ZodError

查看 测试文件 以获取更多详细信息。

用法

const Schema = z.object({ isAdmin: zx.BoolAsString, agreedToTerms: zx.CheckboxAsString, age: zx.IntAsString, cost: zx.NumAsString, }); const parsed = Schema.parse({ isAdmin: 'true', agreedToTerms: 'on', age: '38', cost: '10.99' }); /* parsed = { isAdmin: true, agreedToTerms: true, age: 38, cost: 10.99 } */

附加功能

自定义 URLSearchParams 解析

您可能会遇到像 ?ids[]=1&ids[]=2?ids=1,2 这样的查询字符串 URL,内置的 URLSearchParams 解析无法按照预期处理。

您可以传递一个自定义函数,或使用像 query-string 这样的库来与 Zodix 一起解析它们。

// 创建自定义解析器函数 type ParserFunction = (params: URLSearchParams) => Record<string, string | string[]>; const customParser: ParserFunction = () => { /* ... */ }; // 解析非标准搜索参数 const search = new URLSearchParams(`?ids[]=id1&ids[]=id2`); const { ids } = zx.parseQuery( request, { ids: z.array(z.string()) } { parser: customParser } ); // ids = ['id1', 'id2']

具有多个意图的 Actions

Zod 区分联合类型非常适合处理具有多个意图的 actions,如下所示:

// 这通过 intent 属性添加类型缩小 const Schema = z.discriminatedUnion('intent', [ z.object({ intent: z.literal('delete'), id: z.string() }), z.object({ intent: z.literal('create'), name: z.string() }), ]); export async function action({ request }: ActionArgs) { const data = await zx.parseForm(request, Schema); switch (data.intent) { case 'delete': // data 现在被缩小为 { intent: 'delete', id: string } return; case 'create': // data 现在被缩小为 { intent: 'create', name: string } return; default: // data 现在被缩小为 never。如果缺少某个 case,这里会报错。 const _exhaustiveCheck: never = data; } };

编辑推荐精选

讯飞智文

讯飞智文

一键生成PPT和Word,让学习生活更轻松

讯飞智文是一个利用 AI 技术的项目,能够帮助用户生成 PPT 以及各类文档。无论是商业领域的市场分析报告、年度目标制定,还是学生群体的职业生涯规划、实习避坑指南,亦或是活动策划、旅游攻略等内容,它都能提供支持,帮助用户精准表达,轻松呈现各种信息。

AI办公办公工具AI工具讯飞智文AI在线生成PPTAI撰写助手多语种文档生成AI自动配图热门
讯飞星火

讯飞星火

深度推理能力全新升级,全面对标OpenAI o1

科大讯飞的星火大模型,支持语言理解、知识问答和文本创作等多功能,适用于多种文件和业务场景,提升办公和日常生活的效率。讯飞星火是一个提供丰富智能服务的平台,涵盖科技资讯、图像创作、写作辅助、编程解答、科研文献解读等功能,能为不同需求的用户提供便捷高效的帮助,助力用户轻松获取信息、解决问题,满足多样化使用场景。

热门AI开发模型训练AI工具讯飞星火大模型智能问答内容创作多语种支持智慧生活
Spark-TTS

Spark-TTS

一种基于大语言模型的高效单流解耦语音令牌文本到语音合成模型

Spark-TTS 是一个基于 PyTorch 的开源文本到语音合成项目,由多个知名机构联合参与。该项目提供了高效的 LLM(大语言模型)驱动的语音合成方案,支持语音克隆和语音创建功能,可通过命令行界面(CLI)和 Web UI 两种方式使用。用户可以根据需求调整语音的性别、音高、速度等参数,生成高质量的语音。该项目适用于多种场景,如有声读物制作、智能语音助手开发等。

Trae

Trae

字节跳动发布的AI编程神器IDE

Trae是一种自适应的集成开发环境(IDE),通过自动化和多元协作改变开发流程。利用Trae,团队能够更快速、精确地编写和部署代码,从而提高编程效率和项目交付速度。Trae具备上下文感知和代码自动完成功能,是提升开发效率的理想工具。

AI工具TraeAI IDE协作生产力转型热门
咔片PPT

咔片PPT

AI助力,做PPT更简单!

咔片是一款轻量化在线演示设计工具,借助 AI 技术,实现从内容生成到智能设计的一站式 PPT 制作服务。支持多种文档格式导入生成 PPT,提供海量模板、智能美化、素材替换等功能,适用于销售、教师、学生等各类人群,能高效制作出高品质 PPT,满足不同场景演示需求。

讯飞绘文

讯飞绘文

选题、配图、成文,一站式创作,让内容运营更高效

讯飞绘文,一个AI集成平台,支持写作、选题、配图、排版和发布。高效生成适用于各类媒体的定制内容,加速品牌传播,提升内容营销效果。

热门AI辅助写作AI工具讯飞绘文内容运营AI创作个性化文章多平台分发AI助手
材料星

材料星

专业的AI公文写作平台,公文写作神器

AI 材料星,专业的 AI 公文写作辅助平台,为体制内工作人员提供高效的公文写作解决方案。拥有海量公文文库、9 大核心 AI 功能,支持 30 + 文稿类型生成,助力快速完成领导讲话、工作总结、述职报告等材料,提升办公效率,是体制打工人的得力写作神器。

openai-agents-python

openai-agents-python

OpenAI Agents SDK,助力开发者便捷使用 OpenAI 相关功能。

openai-agents-python 是 OpenAI 推出的一款强大 Python SDK,它为开发者提供了与 OpenAI 模型交互的高效工具,支持工具调用、结果处理、追踪等功能,涵盖多种应用场景,如研究助手、财务研究等,能显著提升开发效率,让开发者更轻松地利用 OpenAI 的技术优势。

Hunyuan3D-2

Hunyuan3D-2

高分辨率纹理 3D 资产生成

Hunyuan3D-2 是腾讯开发的用于 3D 资产生成的强大工具,支持从文本描述、单张图片或多视角图片生成 3D 模型,具备快速形状生成能力,可生成带纹理的高质量 3D 模型,适用于多个领域,为 3D 创作提供了高效解决方案。

3FS

3FS

一个具备存储、管理和客户端操作等多种功能的分布式文件系统相关项目。

3FS 是一个功能强大的分布式文件系统项目,涵盖了存储引擎、元数据管理、客户端工具等多个模块。它支持多种文件操作,如创建文件和目录、设置布局等,同时具备高效的事件循环、节点选择和协程池管理等特性。适用于需要大规模数据存储和管理的场景,能够提高系统的性能和可靠性,是分布式存储领域的优质解决方案。

下拉加载更多