Примитивные типы: string, number, boolean

string

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

Базовое определение:

import { z } from "zod";

const schema = z.string();

Такая схема допускает любое значение типа string и отклоняет все остальные типы: числа, булевы значения, объекты, null, undefined.

Проверка длины строки

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

const usernameSchema = z.string().min(3).max(20);
  • min(n) — минимальная длина строки
  • max(n) — максимальная длина строки

При нарушении ограничений возвращается структурированная ошибка валидации.

Проверка на непустую строку

Частый случай — запрет пустых значений:

const nonEmpty = z.string().min(1);

Альтернативный вариант с явным смыслом:

const nonEmpty = z.string().nonempty();

nonempty() эквивалентен min(1), но делает намерение более явным.

Ограничение формата строки

Регулярные выражения позволяют задавать строгие правила формата:

const codeSchema = z.string().regex(/^[A-Z0-9]{6}$/);

Примеры использования:

  • проверка артикулов
  • коды подтверждения
  • идентификаторы формата UUID-like (в упрощённой форме)
Предустановленные валидаторы формата

Zod включает набор встроенных проверок распространённых форматов:

z.string().email();
z.string().url();
z.string().uuid();

Примеры:

const emailSchema = z.string().email();

const urlSchema = z.string().url();

const idSchema = z.string().uuid();

Эти методы упрощают работу с типовыми данными и уменьшают необходимость в ручных регулярных выражениях.

Преобразование строк

Zod позволяет применять трансформации к строкам:

const trimmed = z.string().transform((val) => val.trim());

Комбинация валидации и преобразования:

const normalizedEmail = z
  .string()
  .email()
  .transform((val) => val.toLowerCase().trim());

Преобразования выполняются после успешной валидации.

number

Тип number используется для валидации числовых значений, включая целые и дробные числа. Он исключает строки, даже если они содержат числовое представление.

Базовое определение:

const schema = z.number();
Проверка диапазонов

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

const ageSchema = z.number().min(0).max(120);
  • min(n) — минимальное значение
  • max(n) — максимальное значение

Дополнительно:

const positive = z.number().positive();
const nonNegative = z.number().nonnegative();
const negative = z.number().negative();
const nonPositive = z.number().nonpositive();
Проверка целых чисел

Для ограничения только целыми значениями:

const intSchema = z.number().int();

Это исключает дробные числа вроде 1.5, 0.1, -3.2.

Проверка кратности

Метод multipleOf проверяет делимость числа:

const evenSchema = z.number().multipleOf(2);

Примеры:

  • 10 проходит
  • 11 не проходит
Особенности NaN и Infinity

По умолчанию NaN, Infinity и -Infinity считаются невалидными:

z.number().safeParse(NaN); // ошибка

При необходимости можно ослабить проверки через предварительные преобразования:

const schema = z.preprocess((val) => Number(val), z.number());
Преобразование чисел

Частая задача — преобразование строкового ввода:

const schema = z.string().transform((val) => Number(val));

Более корректный вариант с валидацией:

const schema = z
  .string()
  .regex(/^\d+$/)
  .transform(Number);

boolean

Тип boolean используется для строгой проверки логических значений.

Базовая схема:

const schema = z.boolean();

Допустимые значения:

  • true
  • false

Любые другие типы (0, 1, "true", "false") отклоняются без преобразования.

Преобразование в boolean

В реальных приложениях часто требуется интерпретация строк или чисел как булевых значений.

Простейший вариант:

const schema = z.coerce.boolean();

Поведение:

  • "true" → true
  • "false" → true (важно: непустая строка)
  • 1 → true
  • 0 → false

Такой подход зависит от внутренних правил JavaScript преобразования типов и требует осторожности.

Явная нормализация значений

Более контролируемый вариант:

const schema = z.string().transform((val) => val === "true");

Расширенная логика:

const schema = z.union([
  z.literal(true),
  z.literal(false),
  z.string().transform((val) => val === "true"),
  z.number().transform((val) => val === 1),
]);
Проверка строгости значений

Для исключения любых не-boolean значений:

const strictBoolean = z.boolean().strict();

Такой подход полезен при работе с API, где требуется жёсткое соответствие контракту данных.

Комбинирование примитивных типов

Примитивные схемы часто используются в составе более сложных структур:

const userSchema = z.object({
  name: z.string().min(2),
  age: z.number().int().min(0),
  isActive: z.boolean(),
});

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

Особенности обработки входных данных

Zod выполняет валидацию в два этапа:

  1. Проверка типа и ограничений
  2. Применение трансформаций (если они определены)

Это влияет на порядок операций:

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

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

Работа с безопасным разбором данных

Каждая примитивная схема поддерживает безопасный режим:

const result = z.string().safeParse(123);

Результат:

{
  success: false,
  error: ZodError
}

Успешный вариант:

{
  success: true,
  data: "value"
}

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

Оглавление