zod

May 25, 2023

zod

Zod 是一个 TypeScript 优先的模式声明和验证库

https://zod.dev/
https://zod.dev/README_ZH

basic

import { z } from "https://deno.land/x/zod/mod.ts";
import { ZodError } from "https://deno.land/x/zod/ZodError.ts";
import { ZodObject } from "https://deno.land/x/zod/mod.ts";

// 原始值

const mySchema = z.string();

mySchema.parse("zod"); // => "zod"

try {
    mySchema.parse(12); // ZodError
} catch (e) {
    if (e instanceof ZodError) {
        // 这个 error 的 message 是 issues 属性 JSON.stringify 得到的
        // 所以直接访问 issue 属性
        console.log(e.issues);
    }
}

mySchema.safeParse("zod"); // => { success: true; data: "zod" }
mySchema.safeParse(12); // => { success: false; error: ZodError }

// 对象

const User = z.object({
    username: z.string(),
});

User.parse({ username: "Ray" }); // => { username: "Ray" }

type User = z.infer<typeof User>; // { username: string }

console.assert(User instanceof ZodObject);

字符串

// 验证
z.string().max(5);
z.string().min(5);
z.string().length(5);
z.string().email();
z.string().url();
z.string().emoji();
z.string().uuid();
z.string().cuid();
z.string().cuid2();
z.string().ulid();
z.string().regex(regex);
z.string().includes(string);
z.string().startsWith(string);
z.string().endsWith(string);
z.string().datetime(); // 默认为 UTC
z.string().datetime({ offset: true }); // 其它选项略
z.string().ip();
z.string().ip({ version: "v4" });
z.string().ip({ version: "v6" });

// 转换
z.string().trim();
z.string().toLowerCase();
z.string().toUpperCase();

// 自定义错误信息
z.string({
    required_error: "Name is required",
    invalid_type_error: "Name must be a string",
});
z.string().url({ message: "Invalid url" });

数字

// 自定义错误信息
const age = z.number({
    required_error: "Age is required",
    invalid_type_error: "Age must be a number",
});

// 验证
z.number().gt(5);
z.number().gte(5); // alias .min(5)
z.number().lt(5);
z.number().lte(5); // alias .max(5)

z.number().int(); // value must be an integer

z.number().positive(); //     > 0
z.number().nonnegative(); //  >= 0
z.number().negative(); //     < 0
z.number().nonpositive(); //  <= 0

z.number().multipleOf(5); // Evenly divisible by 5. Alias .step(5)

z.number().finite(); // value must be finite, not Infinity or -Infinity
z.number().safe(); // value must be between Number.MIN_SAFE_INTEGER and Number.MAX_SAFE_INTEGER

// 自定义错误信息
z.number().lte(5, { message: "this👏is👏too👏big" });

自定义

const px = z.custom<`${number}px`>((val) => {
    return /^\d+px$/.test(val as string);
});

type px = z.infer<typeof px>; // `${number}px`

px.parse("42px"); // "42px"
px.parse("42vw"); // throws;

const myString = z.string().refine((val) => val.length <= 255, {
    message: "String can't be more than 255 characters",
});

const longString = z.string().refine(
    (val) => val.length > 10,
    (val) => ({ message: `${val} is not more than 10 characters` }),
);

异步

若 schema 定义了异步过程，则需要使用特殊的 parse 方法

const userId = z.string().refine(async (id) => {
    // verify that ID exists in database
    return true;
});

const IdToUser = z
    .string()
    .uuid()
    .transform(async (id) => {
        return await getUserById(id);
    });

userId.parseAsync(xxx);
idToUser.safeParseAsync(xxx);

Schema methods

https://zod.dev/?id=schema-methods

←Back to home

This work is licensed under CC BY-NC-SA 4.0