Просто для сложных правил

нужно проверить, что пользователь выбрал хотя бы одну опцию подписки. Стандартные валидаторы вроде z.boolean() не умеют работать с взаимосвязями между полями. Остается писать кастомные функции? Не обязательно.

Решение: .refine()

Метод .refine() позволяет добавить любое кастомное правило к схеме, сохранив элегантность Zod. Его суть:

.refine(validator, { message, path })

• validator: функция, возвращающая boolean (или Promise для асинхронной валидации)
• message: кастомное сообщение об ошибке
• path: куда привязать ошибку (полезно для форм!)

Реальный пример:

export const SubscriptionSchema = z
  .object({
    email: z.string().email(),
    newsletter: z.boolean().optional(),
    promotions: z.boolean().optional(),
    updates: z.boolean().optional(),
  })
  .refine(
    (data) => data.newsletter || data.promotions || data.updates, 
    {
      message: "Выберите хотя бы одну опцию подписки",
      path: ["subscriptionOptions"] // Ошибка привязывается не к полю, а к группе!
    }
  );

• Стандартные правила: email проверяется на корректность, булевы поля опциональны.
• Кастомное правило: .refine() проверяет, что хотя бы одно из полей newsletter, promotions или updates равно true.
• При ошибке:
  • Возвращается понятное сообщение
  • Ошибка привязывается к псевдо-полю subscriptionOptions (удобно для отображения в UI!)

Тестируем:

const result = SubscriptionSchema.safeParse({
  email: "user@example.com",
  newsletter: false,
  promotions: false,
  updates: false,
});

console.log(result.success ? "✔ Valid" : "✕ Error:", result.error?.issues[0]?.message);
// ✕ Error: Выберите хотя бы одну опцию подписки

Почему это круто?

1. Читаемость: Правила валидации как документация.
2. Типобезопасность: z.infer<typeof SubscriptionSchema> автоматически генерирует тип:

type Subscription = {
  email: string;
  newsletter?: boolean;
  promotions?: boolean;
  updates?: boolean;
}

3. Гибкость: Можно проверять любые условия между полями:
   • “Если выбрана рассылка, телефон обязателен”
   • “Сумма заказа > 1000”
4. Интеграция с формами: Кастомный path позволяет подсветить ошибку в нужном месте интерфейса.

С .refine() вы получаете мощь кастомной валидации без boilerplate-кода. Больше никаких велосипедов с ручными проверками после парсинга! Zod позволяет описывать сложные правила в 2-3 строки, сохраняя TypeScript-типы и человекочитаемый синтаксис.

Код валидации должен быть таким же чистым, как и код приложения.
С Zod и .refine() — это реальность.