zod: одна схема, статический тип и рантайм-страж

Одна схема, два выхода

Как не дать типу и стражу разъехаться? Ответ — производить оба из одного определения: редактируете одно, и оба обновляются атомарно. Этим единственным определением и является zod-схема.

zod-схема — это рантайм-значение (объект с методом .parse), которое вдобавок несёт достаточно информации о типе, чтобы z.infer извлёк статический тип. Форму вы пишете один раз:

import { z } from "zod";

const User = z.object({
  id: z.number(),
  name: z.string(),
  email: z.string().email(),
  profile: z.object({ bio: z.string() }).nullable(),
});

type User = z.infer<typeof User>;
// ^? { id: number; name: string; email: string; profile: { bio: string } | null }

Тип User и схема User теперь выведены из одного определения. Второй вещи, которую надо синхронизировать, нет. Добавление z.string() для нового поля обновляет и рантайм-проверку, и выведенный тип одной правкой — расхождение структурно невозможно.

.parse бросает; .safeParse возвращает размеченное объединение

Два способа запустить проверку на границе:

const res = await fetch("/api/user/42");
const json: unknown = await res.json(); // типизируем как unknown, не any

// .parse — бросает ZodError при отказе
const user = User.parse(json); // ^? User  (или бросает)

// .safeParse — возвращает результат, который надо сузить
const result = User.safeParse(json);
if (result.success) {
  result.data; // ^? User  — сужено, валидировано
} else {
  result.error; // ^? ZodError  — пути + сообщения каждого отказа
}

.safeParse возвращает ровно то размеченное объединение, что вы строили руками в уроке 1, — { success: true; data: User } | { success: false; error: ZodError } — только теперь ветка data заработана настоящей рантайм-проверкой, а не утверждена. Используйте .parse на границах доверия, где хотите громкого падения (серверный маршрут, валидирующий своё же чтение из БД), и .safeParse там, где плохое значение — ожидаемый исход, который вы рендерите (ввод формы, сторонний webhook).

Учтите: z.infer возвращает выходной (output) тип. С трансформами вход и выход различаются; увидим это ниже.

Композиция: вложенность, объединения, размеченные объединения

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

const ApiResponse = z.discriminatedUnion("status", [
  z.object({ status: z.literal("ok"), data: User }),
  z.object({ status: z.literal("error"), code: z.number(), message: z.string() }),
]);

type ApiResponse = z.infer<typeof ApiResponse>;
// ^? { status: "ok"; data: User } | { status: "error"; code: number; message: string }

const parsed = ApiResponse.parse(json);
if (parsed.status === "ok") parsed.data; // ^? User

z.discriminatedUnion быстрее и даёт лучшие ошибки, чем обычный z.union, потому что сначала читает дискриминант и валидирует только подходящий член — рантайм-зеркало сужения размеченных объединений, изученного в разделе 02.

Трансформы и уточнения: где вход и выход расходятся

Схема может больше, чем проверять — она может переформировывать и навязывать бизнес-правила:

const DateFromString = z.string().transform((s) => new Date(s));
type In = z.input<typeof DateFromString>;  // ^? string
type Out = z.output<typeof DateFromString>; // ^? Date  (z.infer === output)

const Password = z
  .object({ pw: z.string().min(8), confirm: z.string() })
  .refine((o) => o.pw === o.confirm, { message: "passwords must match", path: ["confirm"] });

transform означает, что значение, которое вы разбираете на входе (строка), отличается от значения, которое получаете на выходе (Date) — поэтому z.infer определён как выходной тип, а z.input существует для формы до трансформа. refine добавляет предикат, который статический тип выразить не может («эти два поля равны»), и привязывает отказ к path поля для отображения в форме (именно так вы подключаете ошибки на уровне полей в работе с формами трека Frontend).