Миграция с Zod

В большинстве случаев перейти с Zod на Valibot очень просто, поскольку у этих API много общего. Это руководство поможет вам шаг за шагом выполнить миграцию и укажет на важные различия.

Официальный codemod

Чтобы сделать миграцию максимально простой, мы создали официальный codemod, который автоматически переносит ваши схемы Zod в Valibot. Просто скопируйте схемы в этот редактор и нажмите кнопку запуска.

Codemod всё ещё находится в бета-версии и может не учитывать все крайние случаи. Если вы столкнулись с проблемами или неожиданным поведением, создайте issue. Также вы можете попробовать исправить проблемы самостоятельно и создать pull request. Исходный код можно найти здесь.

Вы также можете запустить codemod локально, чтобы за один раз перенести всю кодовую базу:

// Preview changes (no writes)
npx @valibot/zod-to-valibot src/**/* --dry

// Apply changes
npx @valibot/zod-to-valibot src/**/*

Замените импорты

После установки Valibot первым делом обновите импорты. Просто замените импорты Zod на импорты Valibot и замените все вхождения z. на v..

// Change this
import { z } from 'zod';
const Schema = z.object({ key: z.string() });

// To this
import * as v from 'valibot';
const Schema = v.object({ key: v.string() });

Измените структуру кода

Одно из главных различий между Zod и Valibot — способ дальнейшей проверки заданного типа. В Zod вы объединяете методы в цепочки, например .email и .endsWith. В Valibot для этого используются конвейеры. Это функция, которая начинается со схемы, за которой следует до 19 действий проверки или преобразования.

// Change this
const Schema = z.string().email().endsWith('@example.com');

// To this
const Schema = v.pipe(v.string(), v.email(), v.endsWith('@example.com'));

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

// Change this
const value = z.string().parse('foo');

// To this
const value = v.parse(v.string(), 'foo');

Рекомендуем ознакомиться с нашим руководством по ментальной модели, чтобы понять, как взаимодействуют отдельные функции модульного API Valibot.

Измените названия

Большинство названий совпадает с названиями в Zod. Однако есть и исключения. В следующей таблице перечислены все изменённые названия.

Другие подробности

Ниже приведены дополнительные сведения, которые могут быть полезны при переходе с Zod на Valibot.

Объекты и кортежи

Чтобы указать, должны ли объекты или кортежи допускать или запрещать неизвестные значения, в Valibot используются разные функции схем. Вместо них в Zod используются методы .passthrough, .strict, .strip, .catchall и .rest. Подробнее см. в руководствах по объектам и массивам.

// Change this
const ObjectSchema = z.object({ key: z.string() }).strict();

// To this
const ObjectSchema = v.strictObject({ key: v.string() });

Сообщения об ошибках

Для отдельных сообщений об ошибках в Zod можно передать строку или объект. Также можно задать разные сообщения для ошибок «required» и «invalid_type». В Valibot вместо этого передаётся одна строка.

// Change this
const StringSchema = z
  .string({ invalid_type_error: 'Not a string' })
  .min(5, { message: 'Too short' });

// To this
const StringSchema = v.pipe(
  v.string('Not a string'),
  v.minLength(5, 'Too short')
);

Приведение типа

Чтобы принудительно привести значение к примитивному типу, в Zod можно использовать метод объекта coerce. В Valibot такого объекта или функции нет. Вместо этого в конвейере используется действие transform в качестве второго аргумента. Это требует явно определить входные данные, что позволяет писать более безопасный код.

// Change this
const NumberSchema = z.coerce.number();

// To this
const NumberSchema = v.pipe(v.unknown(), v.transform(Number));

Вместо unknown, как в предыдущем примере, мы обычно рекомендуем использовать конкретную схему, например string, чтобы повысить безопасность типов. Это позволяет, например, проверить формат строки с помощью decimal перед преобразованием её в число.

const NumberSchema = v.pipe(v.string(), v.decimal(), v.transform(Number));

Асинхронная проверка

Как и Zod, Valibot поддерживает синхронную и асинхронную проверку. Однако API немного отличается. Подробнее см. в руководстве по асинхронной проверке.