Минимальные и максимальные значения

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

Для числовых значений применяется набор методов, задающих нижнюю и верхнюю границы диапазона. Базовый тип описывается через z.number(), после чего к нему добавляются ограничения.

Минимальное значение

Метод min() задаёт нижнюю границу включительно:

z.number().min(10)

Такая схема допускает значения от 10 и выше. Проверка выполняется строго: любое значение меньше 10 считается невалидным.

Максимальное значение

Метод max() задаёт верхнюю границу включительно:

z.number().max(100)

В данном случае допустимы все значения до 100 включительно.

Диапазон

Комбинация min() и max() формирует закрытый диапазон:

z.number().min(10).max(100)

Это эквивалентно интервалу [10, 100].

Строгие неравенства

Для исключения границ используются методы:

  • gt() — строго больше
  • lt() — строго меньше
  • gte() — больше или равно
  • lte() — меньше или равно

Пример:

z.number().gt(0).lt(1)

Такое определение задаёт открытый интервал (0, 1).

Строковые ограничения

Для строк минимальные и максимальные значения определяют длину, а не числовую величину.

Минимальная длина строки

z.string().min(5)

Строка должна содержать не менее пяти символов.

Максимальная длина строки

z.string().max(20)

Строка не может превышать 20 символов.

Диапазон длины

z.string().min(5).max(20)

Формируется ограничение длины строки от 5 до 20 символов включительно.

Массивы

Для массивов минимальные и максимальные значения определяют количество элементов.

Минимальная длина массива

z.array(z.number()).min(1)

Массив должен содержать хотя бы один элемент.

Максимальная длина массива

z.array(z.number()).max(10)

Допускается не более 10 элементов.

Диапазон количества элементов

z.array(z.number()).min(1).max(10)

Ограничение задаёт допустимый размер массива от 1 до 10 элементов.

Дата и временные ограничения

В схемах с датами применяются числовые границы временных меток.

Минимальная дата

z.date().min(new Date("2020-01-01"))

Допустимы даты не ранее указанной.

Максимальная дата

z.date().max(new Date("2030-01-01"))

Ограничение задаёт верхнюю границу диапазона дат.

Диапазон дат

z.date().min(new Date("2020-01-01")).max(new Date("2030-01-01"))

Формируется временной интервал допустимых значений.

Особенности включительности границ

Методы min() и max() по умолчанию включают границы. Это означает, что значение, равное пороговому, считается корректным. Для исключительных границ используются gt() и lt().

Пример различия:

z.number().min(10)   // 10 допустимо
z.number().gt(10)    // 10 недопустимо

Поведение при преобразованиях

При использовании трансформаций (transform) проверка границ выполняется до изменения значения. Это означает, что:

z.number().min(10).transform(v => v * 2)

сначала проверяет исходное значение, и только затем применяет преобразование.

Ограничения в вложенных структурах

Минимальные и максимальные значения применяются независимо в каждом уровне вложенности.

Пример объекта с вложенными ограничениями:

z.object({
  age: z.number().min(18).max(65),
  tags: z.array(z.string().min(2).max(10)).max(5)
})

Здесь одновременно ограничивается числовое поле, длина строк внутри массива и размер массива.

Поведение ошибок в диапазонах

При нарушении минимальных или максимальных границ формируется ошибка валидации с указанием конкретного ограничения. Каждое правило (min, max, gt, lt) создаёт отдельное условие проверки, и все они объединяются в цепочку предикатов, выполняемых последовательно.

Совместимость ограничений

Ограничения могут комбинироваться с другими типами проверок, включая:

  • refine() для пользовательских условий
  • regex для строк
  • nonempty() для массивов и строк

Пример комбинирования:

z.string().min(5).max(20).regex(/^[a-z]+$/)

Здесь одновременно проверяется длина и формат строки.

Пограничные случаи диапазонов

Если минимальное значение превышает максимальное, схема становится логически некорректной:

z.number().min(100).max(10)

Такая конфигурация приводит к невозможному диапазону, при котором ни одно значение не может пройти проверку.

Оглавление