Валидация и типизация с Zod

Детерминированный слой валидации, гарантирующий, что все данные, поступающие в систему, соответствуют определенным архитектурным контрактам.

Архитектура валидации Zod

Преимущества: Zod позволяет объединить рантайм-валидацию с типизацией TypeScript, создавая единый источник истины для форм и данных API.

Структура схем и типов Zod

Соглашения о наименовании

Схемы Zod:
В schema/. Строго пара на операцию: [name]-create.schema.ts ↔ [name]-create-form.types.ts. Только runtime — без экспорта z.infer; ENUM_FORM_* импортируется по прямому пути к файлу, не через barrel ../types.
Типы и Интерфейсы:
В types/[name]-[op]-form.types.ts. Типы форм через z.infer (напр. TEntityCreateSchema) и ENUM_FORM_... живут здесь, не в schema. Схема импортируется только через import type.

01Определение схемы (Schema)

Создание Zod-объекта с использованием i18nKey для локализации сообщений об ошибках.

entities/entity-name/schema/entity-name-create.schema.ts

import { z } from "zod";
import { type TEntityPageKeys, i18nKey } from "@/shared/config";
// прямой путь к form.types — не barrel "../types" (нет цикла schema ↔ types)
import { ENUM_FORM_ENTITY_CREATE } from "../types/entity-name-create-form.types";

const msg = i18nKey<TEntityPageKeys>();
const F = ENUM_FORM_ENTITY_CREATE;

/** Runtime only — never export inferred types from schema files.
 *  Одна схема на операцию: update — в entity-name-update.schema.ts */
export const ENTITY_CREATE_SCHEMA = z.object({
	[F.DESCRIPTION]: z
		.string()
		.trim()
		.min(1, {
			message: msg("form.overview.fields.description.errors.required")
		})
		.min(3, {
			message: msg("form.overview.fields.description.errors.min")
		})
		.max(5000, {
			message: msg("form.overview.fields.description.errors.max")
		}),
});

02Вывод типов (Types)

Использование z.infer для автоматической генерации TypeScript типов из схемы.

entities/entity-name/types/entity-name-create-form.types.ts

import type { FieldValues } from "react-hook-form";
import { z } from "zod";
// только import type — в рантайме зависимость schema → form.types односторонняя
import type { ENTITY_CREATE_SCHEMA } from "../schema";

export const ENUM_FORM_ENTITY_CREATE = {
	DESCRIPTION: "description",
} as const;

export type ENUM_FORM_ENTITY_CREATE_TYPE =
	(typeof ENUM_FORM_ENTITY_CREATE)[keyof typeof ENUM_FORM_ENTITY_CREATE];

/** z.infer and form enums live in types/ — пара к entity-name-create.schema.ts */
export type TEntityCreateSchema = z.infer<typeof ENTITY_CREATE_SCHEMA> &
	FieldValues;

03Интеграция с формой (Usage)

Подключение схемы к react-hook-form через zodResolver.

widgets/entity-name/ui/entity-name.tsx

import { useForm } from "react-hook-form";
import { zodResolver } from "@hookform/resolvers/zod";
import {
	type TEntityCreateSchema,
	ENTITY_CREATE_SCHEMA,
} from "@/entities/entity-name";

const form = useForm<TEntityCreateSchema>({
    resolver: zodResolver(ENTITY_CREATE_SCHEMA),
    mode: "onSubmit"
});