Zod 4 + TypeScript: проверяем форму и JSON из API без неожиданных ошибок

Zod 4 можно освоить на одном небольшом проекте, если сразу видеть вход, действие и результат. Zod проверяет неизвестные данные во время выполнения и одновременно выводит TypeScript-тип из одной схемы. Ниже вы соберёте работающий пример и проверите обычный и граничный сценарии.

Аннотация as User успокаивает редактор, но не меняет JSON из сети: поле age всё ещё может оказаться строкой или исчезнуть. Поэтому отделим настройку, входные данные, основное действие и проверку. В этой статье вы соберёте схему регистрации, функцию разбора FormData и безопасную проверку неизвестного JSON от API. Проверка: корректная форма получает типизированные данные, неверные email и age дают ошибки полей, а сломанный ответ API не проходит дальше.

Как устроен учебный проект Zod 4

Неизвестные данные входят как unknown, schema.safeParse разделяет success и error, а бизнес-функция получает только проверенный тип. Держите ввод, логику и отображение раздельно: тогда каждый этап можно проверить отдельно.

Контрольные точки: схема, форма, проверка и api. Следующий шаг начинается после совпадения с ожидаемым результатом.

От входных данных до видимого результата. Сначала проверяется вход, затем действие и только потом интерфейс.

Собираем рабочий пример шаг за шагом

Пример сверялся с актуальной документацией официальной документации Zod 4 на 19 октября 2026 года. Создайте TypeScript-проект и установите zod. Включите strict в tsconfig и добавьте небольшой файл проверки без UI. Проверьте текущую папку через pwd или Get-Location. Вставьте пример целиком, выполните один раз, затем разбирайте по частям.

import * as z from 'zod'

const Registration = z.object({
  email: z.string().trim().email('Введите корректный email'),
  displayName: z.string().trim().min(2, 'Минимум 2 символа').max(40),
  age: z.coerce.number().int().min(14, 'Минимальный возраст 14').max(120),
})

type Registration = z.infer<typeof Registration>

function parseRegistration(input: unknown): Registration | null {
  const result = Registration.safeParse(input)
  if (!result.success) {
    console.table(result.error.issues.map((issue) => ({
      field: issue.path.join('.'),
      message: issue.message,
    })))
    return null
  }
  return result.data
}

console.log(parseRegistration({
  email: ' student@example.com ',
  displayName: 'Кодик',
  age: '18',
}))

safeParse не бросает исключение для обычной ошибки пользователя, а возвращает discriminated union по полю success. Найдите в примере вход, проверку и место формирования результата.

Что отличает устойчивый проект от случайного запуска. Явные границы делают ошибку локальной и понятной.

Что происходит внутри и почему это работает

Схема является runtime-объектом. TypeScript-тип z.infer существует только при разработке, а Zod реально проверяет значение в браузере или Node.js. Логику держите отдельно от вывода: функция получает аргумент и возвращает значение, а интерфейс показывает его. Coercion удобен для FormData, но может принимать больше входов, чем вы ожидаете. Перед применением определите допустимые представления и добавьте тесты для пустой строки.

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

Проверяем проект и добавляем свою функцию

Подключите схему к HTML-форме и выведите первое сообщение рядом с соответствующим input через issue.path. До правки запишите ожидаемое поведение одним предложением. После граничного теста повторите обычный сценарий.

Схема полезна, когда ошибка превращается в понятное решение: подсветить поле, остановить запрос или записать диагностику ответа API. Полезная правка проходит от нового ввода до видимого результата.

Четыре проверки перед следующим шагом. Каждый следующий этап начинается после наблюдаемого результата.

Что запомнить и куда двигаться дальше

Следующий шаг - разделить форму создания и ответ API, если у них разные поля. Не расширяйте одну схему до огромного универсального объекта. Для закрепления откройте в первом проекте TypeScript, в проверке JSON через Pydantic и в REST API на Bun.

Как изучить тему в Кодике

Повторите unknown, union, generics и обработку формы, затем подключайте Zod на внешней границе. Сначала восстановите главную функцию и проверьте её на трёх значениях.

Уберите as из одного старого API-вызова и замените его явной проверкой unknown через схему. Базовый синтаксис закрепите через курс JavaScript.

Что получится в итоге

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