Перейти к содержанию

Основные принципы использования

На этой странице вы найдете основные сведения о создании схем, анализе данных и использовании выведенных типов. Полную документацию по API схем Zod см. в разделе Определение схем.

Определение схемы

Прежде чем приступить к каким-либо действиям, необходимо определить схему. В целях данного руководства мы будем использовать простую схему объекта.

1
2
3
4
5
6
import * as z from 'zod';

const Player = z.object({
    username: z.string(),
    xp: z.number(),
});

Анализ данных

Для любой схемы Zod используйте .parse для проверки входных данных. Если они действительны, Zod возвращает строго типизированный глубокий клон входных данных.

1
2
Player.parse({ username: 'billie', xp: 100 });
// => returns { username: "billie", xp: 100 }

Если ваша схема использует определенные асинхронные API, такие как async уточнения или трансформации, вам необходимо использовать метод .parseAsync().

1
await Player.parseAsync({ username: 'billie', xp: 100 });

Обработка ошибок

При сбое валидации метод .parse() выдает экземпляр ZodError с подробной информацией о проблемах валидации.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
try {
    Player.parse({ username: 42, xp: '100' });
} catch (error) {
    if (error instanceof z.ZodError) {
        error.issues;
        /*
        [
            {
                expected: 'string',
                code: 'invalid_type',
                path: [ 'username' ],
                message: 'Invalid input: expected string'
            },
            {
                expected: 'number',
                code: 'invalid_type',
                path: [ 'xp' ],
                message: 'Invalid input: expected number'
            }
        ]
        */
    }
}

Чтобы избежать использования блока try/catch, можно использовать метод .safeParse(), который возвращает простой объект результата, содержащий либо успешно проанализированные данные, либо ZodError. Тип результата является дискриминированным объединением, поэтому вы можете удобно обрабатывать оба случая.

1
2
3
4
5
6
7
8
9
const result = Player.safeParse({
    username: 42,
    xp: '100',
});
if (!result.success) {
    result.error; // ZodError instance
} else {
    result.data; // { username: string; xp: number }
}

Если ваша схема использует определенные асинхронные API, такие как async уточнения или преобразования, вам необходимо использовать метод .safeParseAsync().

1
await schema.safeParseAsync('hello');

Вывод типов

Zod выводит статический тип из определений вашей схемы. Вы можете извлечь этот тип с помощью утилиты z.infer<> и использовать его по своему усмотрению.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
const Player = z.object({
    username: z.string(),
    xp: z.number(),
});

// extract the inferred type
type Player = z.infer<typeof Player>;

// use it in your code
const player: Player = { username: 'billie', xp: 100 };

В некоторых случаях типы ввода и вывода схемы могут различаться. Например, API .transform() может преобразовывать ввод из одного типа в другой. В таких случаях вы можете извлекать типы ввода и вывода независимо друг от друга:

1
2
3
4
5
6
7
const mySchema = z.string().transform((val) => val.length);

type MySchemaIn = z.input<typeof mySchema>;
// => string

type MySchemaOut = z.output<typeof mySchema>; // equivalent to z.infer<typeof mySchema>
// number

Теперь, когда мы рассмотрели основы, давайте перейдем к Schema API.

Комментарии