Базовые проверки: min, max, length

Строки: ограничение длины и диапазона символов

Валидация строк в Zod строится вокруг трёх основных методов: min, max и length. Эти методы позволяют задавать минимальную, максимальную или строго фиксированную длину строки.

Основная схема:

import { z } from "zod";

const schema = z.string().min(3).max(10);

В этом случае строка должна содержать не менее 3 символов и не более 10.

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

Метод min(n) задаёт нижнюю границу длины:

const usernameSchema = z.string().min(5);

Поведение:

  • строка "abc" — ошибка
  • строка "hello" — валидна

Вторым аргументом может передаваться сообщение об ошибке:

z.string().min(5, "Минимум 5 символов")

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

Метод max(n) ограничивает верхний предел:

const titleSchema = z.string().max(20);

Поведение:

  • "short title" — валидно
  • строка длиной 50 символов — ошибка

Строгая длина строки

Метод length(n) задаёт фиксированную длину:

const codeSchema = z.string().length(6);

Поведение:

  • "ABC123" — валидно
  • "ABC" — ошибка
  • "ABC1234" — ошибка

Этот метод эквивалентен комбинации min(n).max(n).

Числа: диапазоны значений

Для числовых значений min и max работают как ограничители диапазона.

const ageSchema = z.number().min(18).max(65);

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

z.number().min(0)

Ограничивает значение снизу:

  • -1 — ошибка
  • 0 — валидно
  • 10 — валидно

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

z.number().max(100)
  • 150 — ошибка
  • 100 — валидно

Комбинированный диапазон

z.number().min(10).max(20);

Формирует закрытый интервал [10, 20].

Массивы: контроль размера коллекций

Для массивов методы min, max и length применяются к количеству элементов.

const tagsSchema = z.array(z.string()).min(1).max(5);

Минимальное количество элементов

z.array(z.number()).min(2);
  • [] — ошибка
  • [1] — ошибка
  • [1, 2] — валидно

Максимальное количество элементов

z.array(z.string()).max(3);
  • ["a", "b", "c", "d"] — ошибка
  • ["a", "b"] — валидно

Строгая длина массива

z.array(z.string()).length(4);

Эквивалент:

z.array(z.string()).min(4).max(4);

Вложенные структуры и ограничения длины

Ограничения применяются не только к примитивам, но и к сложным типам.

const userSchema = z.object({
  name: z.string().min(2).max(30),
  roles: z.array(z.string()).min(1).max(3),
});

В этом случае:

  • строка name проверяется на длину
  • массив roles проверяется по количеству элементов

Особенности работы min и max

Порядок вызова

Zod допускает произвольный порядок:

z.string().max(10).min(3)

Результат идентичен стандартному варианту.

Накопление ограничений

Каждый вызов добавляет новое правило в цепочку валидации:

z.string()
  .min(3)
  .max(10)
  .min(5);

Фактически итоговый диапазон становится [5, 10].

Поведение при невалидных значениях

Zod строго разделяет типовые ошибки и ошибки ограничений:

z.string().min(5)
  • 12345 (число) — ошибка типа
  • "abc" — ошибка минимальной длины

Аналогично для чисел:

z.number().max(10)
  • "10" — ошибка типа
  • 20 — ошибка диапазона

Пользовательские сообщения ошибок

Для каждого ограничения можно задать отдельное сообщение:

z.string()
  .min(3, "Слишком короткая строка")
  .max(10, "Слишком длинная строка");

То же применимо к числам и массивам:

z.number().min(0, "Значение не может быть отрицательным");

Типовые комбинации ограничений

Пароль

const passwordSchema = z.string().min(8).max(64);

Пагинация

const pageSchema = z.number().min(1);
const limitSchema = z.number().min(1).max(100);

Теги

const tagsSchema = z.array(z.string().min(1)).max(10);

Частые ошибки при использовании

  • применение length к числу вместо min/max
  • ожидание, что min/max преобразуют типы (Zod не выполняет приведение)
  • дублирование ограничений без учёта итогового диапазона
  • смешивание строковых и числовых проверок в одной схеме без явного типа

Поведение с опциональными значениями

При использовании optional ограничения сохраняются, но применяются только при наличии значения:

z.string().min(3).optional();
  • undefined — валидно
  • "ab" — ошибка
  • "abc" — валидно

Совместимость с transform и preprocess

Ограничения min, max, length применяются после преобразований:

const schema = z.string()
  .transform((val) => val.trim())
  .min(3);

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

Логическая модель ограничений

  • min — нижняя граница допустимого диапазона
  • max — верхняя граница допустимого диапазона
  • length — строго фиксированное значение размера

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

Оглавление