Что такое Zod и зачем нужна runtime-валидация в TypeScript-проекте?

Проблема: TypeScript не защищает на этапе выполнения

TypeScript — статическая система типов. Это значит, что все проверки происходят во время компиляции и полностью исчезают из скомпилированного JavaScript-кода. Если сервер вернул объект с неожиданной структурой, TypeScript об этом не узнает — ваш код просто получит undefined там, где ожидал строку, и упадёт или отработает некорректно.

Основные источники «опасных» данных:

• Ответы внешних и внутренних API
• Данные из форм пользователя
• Переменные окружения (process.env)
• Данные из localStorage или sessionStorage
• Параметры URL и query-строки

Что такое Zod

Zod — TypeScript-first библиотека для объявления и валидации схем данных. Её ключевые принципы:

1. Схема = источник истины. Вы описываете структуру один раз, а Zod автоматически выводит TypeScript-тип через z.infer<typeof schema>.
2. Валидация в рантайме. Метод parse или safeParse проверяет реальные данные и бросает подробную ошибку при несоответствии.
3. Нулевые зависимости, маленький бандл. Zod не тянет лишних пакетов.

Базовое использование

import { z } from 'zod';

// Объявляем схему
const UserSchema = z.object({
  id: z.number().int().positive(),
  email: z.string().email(),
  role: z.enum(['admin', 'user', 'guest']),
  createdAt: z.string().datetime().optional(),
});

// Выводим TypeScript-тип автоматически — не дублируем код
type User = z.infer<typeof UserSchema>;

// parse — бросает ZodError при ошибке
const user = UserSchema.parse(rawDataFromApi);

// safeParse — возвращает { success, data } | { success: false, error }
const result = UserSchema.safeParse(rawDataFromApi);
if (!result.success) {
  console.error(result.error.flatten());
} else {
  console.log(result.data.email); // тип User гарантирован
}

Интеграция с fetch-запросами

async function fetchUser(id: number): Promise<User> {
  const response = await fetch(`/api/users/${id}`);
  const json = await response.json(); // тип unknown

  // Без Zod пришлось бы доверять API или писать ручные проверки
  return UserSchema.parse(json); // гарантируем корректность
}

Валидация переменных окружения

const EnvSchema = z.object({
  DATABASE_URL: z.string().url(),
  PORT: z.coerce.number().default(3000), // coerce конвертирует строку в число
  NODE_ENV: z.enum(['development', 'production', 'test']),
});

// Падаем при старте приложения, а не в рантайме через час работы
export const env = EnvSchema.parse(process.env);

Преобразования и трансформации

Zod умеет не только валидировать, но и преобразовывать данные:

const DateSchema = z.string().transform((val) => new Date(val));
// parse вернёт Date, а не string

Сравнение с альтернативами

• Yup — похожий API, но хуже интегрируется с TypeScript (менее точные выводимые типы).
• io-ts — функциональный стиль, крутой вывод типов, но сложнее для освоения.
• class-validator — декораторы на классах, требует reflect-metadata, не работает с plain объектами.
• Valibot — более легковесная альтернатива Zod с модульным API.

Zod стал стандартом de facto благодаря простому API и первоклассной поддержке TypeScript.