Validator API

Validator API в TanStack Router предназначен для строгой валидации параметров маршрутов, запросов и данных состояния маршрутов. Он позволяет обеспечить соответствие входных данных ожидаемым типам и структурам, предотвращая ошибки на этапе навигации и упрощая обработку данных внутри компонентов.

Создание валидаторов

В TanStack Router валидаторы создаются с помощью объектов схем, совместимых с различными библиотеками валидации, включая zod и superstruct. Основная цель валидатора — определить структуру данных и правила проверки.

Пример использования zod для параметра маршрута:

import { z } from 'zod';
import { createRouter, Route } from '@tanstack/router';

const userRoute = new Route({
  path: '/user/:id',
  validate: {
    params: z.object({
      id: z.string().regex(/^\d+$/), // id должен быть числом в строковом формате
    }),
  },
});

Ключевые моменты:

params — валидатор для параметров маршрута.
query — валидатор для query-параметров.
body — валидатор для POST-запросов (если используется в SSR или API-маршрутах).
Любая ошибка валидации приводит к прерыванию навигации с возможностью обработки ошибки.

Валидация query-параметров

Query-параметры часто приходят в виде строк, поэтому их валидация необходима для безопасного преобразования в нужные типы.

Пример:

const postsRoute = new Route({
  path: '/posts',
  validate: {
    query: z.object({
      page: z.string().transform(val => parseInt(val, 10)).default('1'),
      search: z.string().optional(),
    }),
  },
});

Метод transform позволяет автоматически преобразовать строковые значения query в числа.
default задаёт значение по умолчанию при отсутствии параметра.
optional делает параметр необязательным.

Валидация состояния маршрута

В TanStack Router можно передавать объект состояния при навигации. Валидатор состояния обеспечивает строгий контракт данных между компонентами.

Пример:

const dashboardRoute = new Route({
  path: '/dashboard',
  validate: {
    state: z.object({
      theme: z.enum(['light', 'dark']),
      showSidebar: z.boolean().default(true),
    }),
  },
});

Любое отклонение от схемы приведёт к ошибке валидации.
Значения по умолчанию позволяют избежать проверки на undefined.

Обработка ошибок валидации

Ошибки валидации можно обрабатывать через механизм onValidateError или через глобальный обработчик маршрутизатора.

const router = createRouter({
  routes: [userRoute, postsRoute],
  onValidateError: ({ error, route }) => {
    console.error(`Ошибка валидации на маршруте ${route.path}:`, error);
  },
});

error содержит объект с подробной информацией о нарушении схемы.
Можно перенаправить пользователя на страницу ошибки или показать уведомление.

Композиция валидаторов

TanStack Router поддерживает композицию схем для сложных маршрутов:

const idValidator = z.object({ id: z.string().regex(/^\d+$/) });
const paginationValidator = z.object({ page: z.number().min(1) });

const combinedRoute = new Route({
  path: '/items/:id',
  validate: {
    params: idValidator,
    query: paginationValidator,
  },
});

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

Интеграция с React-компонентами

Валидация тесно связана с хуками TanStack Router, например useParams, useQuery, useState. После успешной валидации возвращается типизированный объект с гарантированной структурой:

import { useParams } from '@tanstack/router';

function UserProfile() {
  const params = useParams();
  // params.id уже валидирован и соответствует заданной схеме
  return <div>ID пользователя: {params.id}</div>;
}

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

Валидация асинхронных данных

Validator API поддерживает асинхронные проверки через refine или superRefine в Zod:

const asyncRoute = new Route({
  path: '/check/:id',
  validate: {
    params: z.object({
      id: z.string().refine(async id => {
        const exists = await fetch(`/api/check/${id}`).then(res => res.ok);
        return exists;
      }, { message: 'ID не найден' }),
    }),
  },
});

Асинхронные проверки позволяют интегрировать серверные валидации.
Ошибки асинхронной проверки обрабатываются так же, как синхронные.