code-ai-installer 3.0.0 → 4.0.0

package/domains/development/.agents/skills/tanstack-beast-practices/SKILL.md

@@ -1,476 +1,181 @@
----
-name: tanstack-beast-practices
-description: TanStack (Query v5, Table v8, Virtual v3): кэширование, инвалидация, пагинация, infinite scroll, серверные фильтры/сортировка, виртуализация больших списков. Используй этот скилл при любой работе с TanStack Query, TanStack Table или TanStack Virtual — при написании fetcher-слоя, настройке кэша, построении таблиц с серверной пагинацией, виртуальных списков и при вопросах «как правильно сделать X с TanStack».
----
-
-# Skill: TanStack Beast Practices
-
-Копипаст-паттерны для предсказуемой работы с данными, таблицами и виртуализацией.
-
-> [!IMPORTANT]
-> **MCP-приоритет:** Если доступен MCP-сервер `tanstack-docs`, **всегда используй его инструменты** (`tanstack_doc`, `tanstack_search_docs`, `listTanStackAddOns`, `getAddOnDetails`, `createTanStackApplication`) **первыми** — они дают актуальную документацию прямо из официальных источников TanStack. Используй паттерны этого скилла как fallback или как дополнительный контекст по архитектуре (fetcher/adapter/hook, queryKey factory, оптимистичные обновления, виртуализация), когда MCP недоступен или не содержит нужной информации.
-
-**Разделы:**
-1. [Query: архитектура fetcher/adapter](#1-query-архитектура)
-2. [Query: кэширование и staleTime](#2-query-кэш)
-3. [Query: мутации и инвалидация](#3-query-мутации)
-4. [Query: пагинация и infinite scroll](#4-query-пагинация)
-5. [Table: серверная пагинация/сортировка/фильтры](#5-table)
-6. [Virtual: большие списки](#6-virtual)
-
----
-
-## 1. Query: Архитектура
-
-### ✅ DO: отдельные слои fetcher → adapter → hook
-```ts
-// ─── 1. fetcher: чистый HTTP, без бизнес-логики ───────────────────
-// src/api/users.api.ts
-export async function fetchUsersApi(params: UsersQueryParams): Promise<UsersApiResponse> {
-  const qs = new URLSearchParams(params as any).toString();
-  const res = await fetch(`/api/users?${qs}`);
-  if (!res.ok) throw new Error(`HTTP ${res.status}`);
-  return res.json();
-}
-
-// ─── 2. adapter: маппинг API-модели → доменную ────────────────────
-// src/api/users.adapter.ts
-export function adaptUser(raw: UserApiModel): User {
-  return {
-    id:        raw.user_id,          // snake_case → camelCase
-    fullName:  `${raw.first_name} ${raw.last_name}`,
-    createdAt: new Date(raw.created_at),
-  };
-}
-
-// ─── 3. hook: queryKey + queryFn + transform ──────────────────────
-// src/hooks/useUsers.ts
-export function useUsers(params: UsersQueryParams) {
-  return useQuery({
-    queryKey: ["users", params],          // ключ включает параметры
-    queryFn:  () => fetchUsersApi(params),
-    select:   data => data.items.map(adaptUser), // transform здесь, не в компоненте
-  });
-}
-```
-
-### ✅ DO: queryKey factory — один источник правды для ключей
-```ts
-// src/api/users.keys.ts
-export const userKeys = {
-  all:     ()          => ["users"]                    as const,
-  lists:   ()          => [...userKeys.all(), "list"]  as const,
-  list:    (p: Params) => [...userKeys.lists(), p]     as const,
-  details: ()          => [...userKeys.all(), "detail"] as const,
-  detail:  (id: string)=> [...userKeys.details(), id]  as const,
-};
-
-// Использование:
-useQuery({ queryKey: userKeys.list(params), queryFn: ... });
-
-// Инвалидация всех списков разом:
-qc.invalidateQueries({ queryKey: userKeys.lists() });
-
-// ❌ Плохо: магические строки разбросаны по компонентам
-useQuery({ queryKey: ["users", "list", page], ... }); // дублирование и опечатки
-```
-
----
-
-## 2. Query: Кэш
-
-### ✅ DO: осознанно выставлять staleTime и gcTime
-```ts
-// src/lib/queryClient.ts
-export const queryClient = new QueryClient({
-  defaultOptions: {
-    queries: {
-      staleTime: 60 * 1000,   // данные свежие 1 минуту — нет лишних фетчей при навигации
-      gcTime:    5 * 60 * 1000, // мусор собирается через 5 минут
-      retry: 2,
-      refetchOnWindowFocus: false, // отключи если данные не real-time
-    },
-  },
-});
-
-// ✅ Переопределение для конкретного хука
-export function useUserProfile(id: string) {
-  return useQuery({
-    queryKey: userKeys.detail(id),
-    queryFn:  () => fetchUserProfile(id),
-    staleTime: 5 * 60 * 1000, // профиль меняется редко — кэш 5 минут
-  });
-}
-
-// ✅ Real-time данные — без кэша
-export function useLiveStats() {
-  return useQuery({
-    queryKey: ["live-stats"],
-    queryFn:  fetchLiveStats,
-    staleTime: 0,               // всегда stale
-    refetchInterval: 5000,      // поллинг каждые 5 секунд
-  });
-}
-```
-
-### ✅ DO: prefetch для предзагрузки при ховере
-```ts
-function UserLink({ userId }: { userId: string }) {
-  const qc = useQueryClient();
-
-  return (
-    <a
-      href={`/users/${userId}`}
-      onMouseEnter={() => {
-        // ✅ Предзагружаем данные до клика — переход кажется мгновенным
-        qc.prefetchQuery({
-          queryKey: userKeys.detail(userId),
-          queryFn:  () => fetchUserProfile(userId),
-          staleTime: 60 * 1000,
-        });
-      }}
-    >
-      View Profile
-    </a>
-  );
-}
-```
-
----
-
-## 3. Query: Мутации и Инвалидация
-
-### ✅ DO: оптимистичное обновление + rollback
-```ts
-export function useUpdateUser() {
-  const qc = useQueryClient();
-
-  return useMutation({
-    mutationFn: (data: UpdateUserDto) =>
-      fetch(`/api/users/${data.id}`, {
-        method: "PATCH",
-        body: JSON.stringify(data),
-        headers: { "Content-Type": "application/json" },
-      }).then(r => { if (!r.ok) throw new Error(`HTTP ${r.status}`); return r.json(); }),
-
-    // ✅ Оптимистично обновляем кэш ДО ответа сервера
-    onMutate: async (data) => {
-      await qc.cancelQueries({ queryKey: userKeys.detail(data.id) });
-
-      const previous = qc.getQueryData<User>(userKeys.detail(data.id));
-      qc.setQueryData(userKeys.detail(data.id), (old: User) => ({ ...old, ...data }));
-
-      return { previous }; // контекст для rollback
-    },
-
-    // ✅ Откат при ошибке
-    onError: (_err, data, ctx) => {
-      if (ctx?.previous) {
-        qc.setQueryData(userKeys.detail(data.id), ctx.previous);
-      }
-    },
-
-    // ✅ Синхронизация с сервером в любом случае
-    onSettled: (_data, _err, data) => {
-      qc.invalidateQueries({ queryKey: userKeys.detail(data.id) });
-    },
-  });
-}
-```
-
-### ✅ DO: инвалидация нескольких ключей после мутации
-```ts
-export function useDeleteUser() {
-  const qc = useQueryClient();
-
-  return useMutation({
-    mutationFn: (id: string) =>
-      fetch(`/api/users/${id}`, { method: "DELETE" }).then(r => {
-        if (!r.ok) throw new Error(`HTTP ${r.status}`);
-      }),
-
-    onSuccess: (_data, id) => {
-      // ✅ Инвалидируем список И детальную страницу
-      qc.invalidateQueries({ queryKey: userKeys.lists() });
-      qc.removeQueries({ queryKey: userKeys.detail(id) }); // удаляем из кэша совсем
-    },
-  });
-}
-```
-
----
-
-## 4. Query: Пагинация и Infinite Scroll
-
-### ✅ DO: серверная пагинация через keepPreviousData
-```ts
-export function useUsersList(page: number, pageSize = 20) {
-  return useQuery({
-    queryKey: userKeys.list({ page, pageSize }),
-    queryFn:  () => fetchUsersApi({ page, pageSize }),
-    placeholderData: keepPreviousData, // ✅ нет "мигания" при смене страницы
-    staleTime: 30 * 1000,
-  });
-}
-
-// Использование в компоненте
-function UsersTable() {
-  const [page, setPage] = useState(1);
-  const { data, isFetching } = useUsersList(page);
-
-  return (
-    <>
-      {isFetching && <Spinner size="sm" />} {/* индикатор без блокировки UI */}
-      <Table rows={data?.items ?? []} />
-      <Pagination
-        current={page}
-        total={data?.meta.total ?? 0}
-        onChange={setPage}
-      />
-    </>
-  );
-}
-```
-
-### ✅ DO: infinite scroll через useInfiniteQuery
-```ts
-export function useInfiniteUsers(search: string) {
-  return useInfiniteQuery({
-    queryKey:     userKeys.list({ search }),
-    queryFn:      ({ pageParam }) => fetchUsersApi({ search, cursor: pageParam }),
-    initialPageParam: undefined as string | undefined,
-    getNextPageParam: last => last.meta.nextCursor ?? undefined,
-    staleTime: 60 * 1000,
-  });
-}
-
-function InfiniteUsersList() {
-  const { data, fetchNextPage, hasNextPage, isFetchingNextPage } = useInfiniteUsers("");
-  const ref = useRef<HTMLDivElement>(null);
-
-  // ✅ IntersectionObserver — грузим следующую страницу при достижении конца
-  useEffect(() => {
-    const el = ref.current;
-    if (!el) return;
-    const obs = new IntersectionObserver(
-      ([entry]) => { if (entry.isIntersecting && hasNextPage) fetchNextPage(); },
-      { threshold: 0.1 }
-    );
-    obs.observe(el);
-    return () => obs.disconnect();
-  }, [fetchNextPage, hasNextPage]);
-
-  const users = data?.pages.flatMap(p => p.items) ?? [];
-
-  return (
-    <ul>
-      {users.map(u => <li key={u.id}>{u.fullName}</li>)}
-      <div ref={ref}>
-        {isFetchingNextPage && <Spinner />}
-      </div>
-    </ul>
-  );
-}
-```
-
----
-
-## 5. Table
-
-### ✅ DO: серверная пагинация + сортировка + фильтры
-```ts
-// ─── State: URL как источник правды для фильтров/пагинации ─────────
-function useTableState() {
-  const [sorting,    setSorting]    = useState<SortingState>([]);
-  const [pagination, setPagination] = useState<PaginationState>({ pageIndex: 0, pageSize: 20 });
-  const [columnFilters, setColumnFilters] = useState<ColumnFiltersState>([]);
-
-  return { sorting, setSorting, pagination, setPagination, columnFilters, setColumnFilters };
-}
-
-// ─── Параметры запроса из состояния таблицы ────────────────────────
-function tableStateToQueryParams(
-  sorting: SortingState,
-  pagination: PaginationState,
-  columnFilters: ColumnFiltersState
-): UsersQueryParams {
-  return {
-    page:     pagination.pageIndex + 1,
-    pageSize: pagination.pageSize,
-    sortBy:   sorting[0]?.id,
-    sortDir:  sorting[0]?.desc ? "desc" : "asc",
-    ...Object.fromEntries(columnFilters.map(f => [f.id, f.value])),
-  };
-}
-
-// ─── Таблица ───────────────────────────────────────────────────────
-const columns: ColumnDef<User>[] = [
-  { accessorKey: "fullName", header: "Name", enableSorting: true },
-  { accessorKey: "email",    header: "Email", enableColumnFilter: true },
-  {
-    accessorKey: "createdAt",
-    header: "Created",
-    cell: ({ getValue }) => getValue<Date>().toLocaleDateString("ru-RU"),
-  },
-];
-
-function UsersDataTable() {
-  const ts = useTableState();
-  const params = tableStateToQueryParams(ts.sorting, ts.pagination, ts.columnFilters);
-  const { data, isFetching } = useUsersList(params);
-
-  const table = useReactTable({
-    data:        data?.items ?? [],
-    columns,
-    rowCount:    data?.meta.total ?? 0,
-    state:       { sorting: ts.sorting, pagination: ts.pagination, columnFilters: ts.columnFilters },
-    manualSorting:    true, // ✅ серверная сортировка
-    manualPagination: true, // ✅ серверная пагинация
-    manualFiltering:  true, // ✅ серверная фильтрация
-    onSortingChange:       ts.setSorting,
-    onPaginationChange:    ts.setPagination,
-    onColumnFiltersChange: ts.setColumnFilters,
-    getCoreRowModel:       getCoreRowModel(),
-  });
-
-  return (
-    <div>
-      {isFetching && <div className="loading-bar" />}
-      <table>
-        <thead>
-          {table.getHeaderGroups().map(hg => (
-            <tr key={hg.id}>
-              {hg.headers.map(h => (
-                <th key={h.id} onClick={h.column.getToggleSortingHandler()}>
-                  {flexRender(h.column.columnDef.header, h.getContext())}
-                  {h.column.getIsSorted() === "asc" ? " ↑" : h.column.getIsSorted() === "desc" ? " ↓" : ""}
-                </th>
-              ))}
-            </tr>
-          ))}
-        </thead>
-        <tbody>
-          {table.getRowModel().rows.map(row => (
-            <tr key={row.id}>
-              {row.getVisibleCells().map(cell => (
-                <td key={cell.id}>
-                  {flexRender(cell.column.columnDef.cell, cell.getContext())}
-                </td>
-              ))}
-            </tr>
-          ))}
-        </tbody>
-      </table>
-      <div>
-        <button onClick={() => table.previousPage()} disabled={!table.getCanPreviousPage()}>←</button>
-        <span>Page {table.getState().pagination.pageIndex + 1} of {table.getPageCount()}</span>
-        <button onClick={() => table.nextPage()} disabled={!table.getCanNextPage()}>→</button>
-      </div>
-    </div>
-  );
-}
-```
-
-### ❌ DON'T: клиентская сортировка/пагинация на больших данных
-```ts
-// ❌ Плохо: грузим всё, потом сортируем в браузере
-useQuery({ queryFn: () => fetchAllUsers() }); // 10к+ записей в памяти браузера
-// ✅ manualSorting + manualPagination + серверный запрос с параметрами
-```
-
----
-
-## 6. Virtual
-
-### ✅ DO: useVirtualizer для длинных списков
-```tsx
-import { useVirtualizer } from "@tanstack/react-virtual";
-
-function VirtualUsersList({ users }: { users: User[] }) {
-  const parentRef = useRef<HTMLDivElement>(null);
-
-  const virtualizer = useVirtualizer({
-    count:            users.length,
-    getScrollElement: () => parentRef.current,
-    estimateSize:     () => 56,   // примерная высота строки в px
-    overscan:         5,          // рендерим 5 строк за экраном (плавность)
-  });
-
-  return (
-    <div ref={parentRef} style={{ height: "600px", overflowY: "auto" }}>
-      {/* контейнер полной высоты — браузер рисует правильный scrollbar */}
-      <div style={{ height: virtualizer.getTotalSize(), position: "relative" }}>
-        {virtualizer.getVirtualItems().map(vRow => (
-          <div
-            key={vRow.index}
-            style={{
-              position:  "absolute",
-              top:       vRow.start,
-              width:     "100%",
-              height:    vRow.size,
-            }}
-          >
-            <UserRow user={users[vRow.index]} />
-          </div>
-        ))}
-      </div>
-    </div>
-  );
-}
-```
-
-### ✅ DO: динамические высоты строк через measureElement
-```tsx
-const virtualizer = useVirtualizer({
-  count:            items.length,
-  getScrollElement: () => parentRef.current,
-  estimateSize:     () => 80,
-  measureElement:   el => el.getBoundingClientRect().height, // ✅ реальная высота
-});
-
-// В рендере строки:
-<div ref={virtualizer.measureElement} data-index={vRow.index}>
-  <VariableHeightRow item={items[vRow.index]} />
-</div>
-```
-
-### ✅ DO: виртуализация таблицы (комбо Table + Virtual)
-```tsx
-// ✅ Получаем строки из TanStack Table, виртуализируем через Virtual
-const rows = table.getRowModel().rows;
-
-const rowVirtualizer = useVirtualizer({
-  count:            rows.length,
-  getScrollElement: () => tableContainerRef.current,
-  estimateSize:     () => 40,
-  overscan:         10,
-});
-
-// Рендерим только видимые строки:
-{rowVirtualizer.getVirtualItems().map(vRow => {
-  const row = rows[vRow.index];
-  return (
-    <tr key={row.id} style={{ height: vRow.size, transform: `translateY(${vRow.start}px)` }}>
-      {row.getVisibleCells().map(cell => (
-        <td key={cell.id}>{flexRender(cell.column.columnDef.cell, cell.getContext())}</td>
-      ))}
-    </tr>
-  );
-})}
-```
-
-### Правило выбора: пагинация vs виртуализация
-| Сценарий | Решение |
-|---|---|
-| Таблица с навигацией, SEO, закладками на страницу | Серверная пагинация |
-| Лента/список без чёткого понятия "страница" | Infinite scroll |
-| Dropdown с поиском, 1000+ опций | Виртуализация |
-| Таблица с 10k+ строк без пагинации | Виртуализация |
-| Смешанный UX: таблица + докрутка до конца | Table + Virtual |
-
----
-
-## См. также
-- `react-beast-practices` → виртуализация (базовый пример)
-- `typescript-beast-practices` → типизация generic запросов
-- `dev-reference-snippets` → раздел 6 (базовые примеры useQuery/useMutation)
+---
+name: tanstack-beast-practices
+description: "TanStack (Query v5, Table v8, Virtual v3): кэширование, инвалидация, пагинация, infinite scroll, серверные фильтры/сортировка, виртуализация больших списков. Используй этот скилл при любой работе с TanStack Query, TanStack Table или TanStack Virtual — при написании fetcher-слоя, настройке кэша, построении таблиц с серверной пагинацией, виртуальных списков и при вопросах «как правильно сделать X с TanStack»."
+type: discretionary
+domain: development
+owners:
+  - senior_full_stack
+gates:
+  - DEV
+tech:
+  - tanstack
+topic:
+  - general
+triggers:
+  - TanStack Query
+  - TanStack Table
+  - TanStack Virtual
+  - инвалидация кэша
+  - infinite scroll
+  - виртуализация списка
+  - серверная пагинация
+related:
+  - tanstack-beast-practices-reference
+  - react-beast-practices
+  - typescript-beast-practices
+  - state-zustand-beast-practices
+  - state-rtk-beast-practices
+  - mongodb-mongoose-best-practices
+  - node-express-beast-practices
+  - testing-strategy-js
+  - es2025-beast-practices
+  - tooling-bun-biome
+  - dev-reference-snippets
+budget_lines: 300
+schema_version: 1
+---
+
+
+# Skill: TanStack Beast Practices
+
+Workflow-скилл: когда тянуться к Query/Table/Virtual, как разложить data-слой, как выбирать между серверной пагинацией и виртуализацией. Готовые шаблоны — в `tanstack-beast-practices-reference`.
+
+> [!IMPORTANT]
+> **MCP-приоритет:** Если доступен MCP-сервер `tanstack-docs`, **всегда используй его инструменты** (`tanstack_doc`, `tanstack_search_docs`, `listTanStackAddOns`, `getAddOnDetails`, `createTanStackApplication`) **первыми** — они дают актуальную документацию прямо из официальных источников TanStack. Используй паттерны этого скилла как fallback или как дополнительный контекст по архитектуре (fetcher/adapter/hook, queryKey factory, оптимистичные обновления, виртуализация), когда MCP недоступен или не содержит нужной информации.
+
+**Разделы:**
+1. [Query: архитектура fetcher/adapter/hook](#1-query-архитектура)
+2. [Query: кэш и staleTime](#2-query-кэш)
+3. [Query: мутации и инвалидация](#3-query-мутации)
+4. [Query: пагинация и infinite scroll](#4-query-пагинация)
+5. [Table: серверные режимы](#5-table)
+6. [Virtual: большие списки](#6-virtual)
+
+---
+
+## 1. Query: Архитектура
+
+**Правило слоёв (fetcher → adapter → hook):**
+- **fetcher** — чистый HTTP, без бизнес-логики и без TanStack-зависимостей. Один файл на ресурс (`users.api.ts`).
+- **adapter** — маппинг API-модели → доменную (snake_case → camelCase, ISO-строки → Date). Без побочных эффектов.
+- **hook** — `useQuery` с `queryKey + queryFn + select` (transform через `select`, не в компоненте).
+
+**queryKey factory — единственный источник правды для ключей:**
+- Один объект `userKeys = { all, lists, list(p), details, detail(id) }` на ресурс.
+- В компонентах — **только** `userKeys.list(params)`, никаких магических строк.
+- Инвалидация по группам: `qc.invalidateQueries({ queryKey: userKeys.lists() })`.
+
+➡ Шаблоны: `tanstack-beast-practices-reference` § 1.
+
+---
+
+## 2. Query: Кэш
+
+**Осознанно выставляй `staleTime` и `gcTime`:**
+- **`staleTime`** — как долго данные считаются свежими (нет refetch при навигации). Default 0 = всегда stale.
+- **`gcTime`** (бывший `cacheTime`) — как долго мусор живёт после отписки последнего наблюдателя.
+- **Default по проекту** настраивай в `QueryClient` (`staleTime: 60_000`, `gcTime: 5*60_000`, `refetchOnWindowFocus: false` если не real-time).
+- **Real-time** — `staleTime: 0` + `refetchInterval` для поллинга.
+- **Редко меняющийся профиль** — переопределяй `staleTime` в конкретном хуке (5 минут+).
+
+**Prefetch на hover** — `qc.prefetchQuery` в `onMouseEnter`: переход кажется мгновенным.
+
+➡ Шаблоны: `tanstack-beast-practices-reference` § 2.
+
+---
+
+## 3. Query: Мутации и инвалидация
+
+**Шаблон оптимистичного обновления:**
+1. `onMutate` — `cancelQueries` для затронутого ключа, snapshot через `getQueryData`, оптимистичный `setQueryData`, вернуть `{ previous }` как контекст.
+2. `onError(_err, vars, ctx)` — откат через `setQueryData(key, ctx.previous)`.
+3. `onSettled` — финальная синхронизация: `invalidateQueries({ queryKey })`.
+
+**Инвалидация нескольких ключей:**
+- `invalidateQueries({ queryKey: userKeys.lists() })` — все списки разом.
+- `removeQueries({ queryKey: userKeys.detail(id) })` — удалить детальную страницу из кэша после `DELETE`.
+
+**Иерархия ключей решает всё:** ключ-префикс инвалидирует всех потомков, чего нельзя сделать через магические строки.
+
+➡ Шаблоны: `tanstack-beast-practices-reference` § 3.
+
+---
+
+## 4. Query: Пагинация и infinite scroll
+
+**Решение зависит от UX:**
+
+| Сценарий | Решение | Ключевая опция |
+|---|---|---|
+| Таблица со страницами и URL | Серверная пагинация через `useQuery` | `placeholderData: keepPreviousData` |
+| Лента/feed, докрутка вниз | Infinite scroll через `useInfiniteQuery` | `getNextPageParam: last => last.meta.nextCursor` |
+
+**Серверная пагинация:**
+- `queryKey` включает `{ page, pageSize }` — каждая страница = свой кэш-эпизод.
+- `placeholderData: keepPreviousData` убирает «мигание» при смене страницы (старые данные видны до прихода новых).
+- `isFetching` (а не `isLoading`) для индикатора загрузки без блокировки.
+
+**Infinite scroll:**
+- Cursor-based (не offset) — стабилен при вставках в начало списка.
+- `IntersectionObserver` на «sentinel» div → `fetchNextPage()` при `entry.isIntersecting && hasNextPage`.
+- Flatten страниц: `data?.pages.flatMap(p => p.items) ?? []`.
+
+➡ Шаблоны: `tanstack-beast-practices-reference` § 4.
+
+---
+
+## 5. Table
+
+**Правило большого пальца:** при >50 строках всегда серверная сторона.
+
+**Включай `manual*` режимы вместе:**
+- `manualSorting: true` + `manualPagination: true` + `manualFiltering: true` — Table перестаёт обрабатывать данные сам и отдаёт состояние через `onSortingChange / onPaginationChange / onColumnFiltersChange`.
+- `rowCount: data?.meta.total ?? 0` — для корректной работы кнопок пагинации с серверным total.
+- Маппинг состояния → query params вынеси в отдельную функцию `tableStateToQueryParams(sorting, pagination, columnFilters)`.
+
+**URL как источник правды** для фильтров и пагинации — открытая ссылка должна воспроизвести то же представление.
+
+**❌ Не делай клиентскую сортировку/пагинацию на больших данных:** `fetchAllUsers()` загружает 10k+ записей в память браузера.
+
+➡ Шаблоны: `tanstack-beast-practices-reference` § 5.
+
+---
+
+## 6. Virtual
+
+**Правило выбора — пагинация vs виртуализация:**
+
+| Сценарий | Решение |
+|---|---|
+| Таблица с навигацией, SEO, закладками на страницу | Серверная пагинация |
+| Лента/список без чёткого понятия «страница» | Infinite scroll |
+| Dropdown с поиском, 1000+ опций | Виртуализация |
+| Таблица с 10k+ строк без пагинации | Виртуализация |
+| Смешанный UX: таблица + докрутка до конца | Table + Virtual (комбо) |
+
+**Канонические параметры `useVirtualizer`:**
+- `count` — общее количество элементов.
+- `getScrollElement: () => parentRef.current` — родительский overflow-контейнер.
+- `estimateSize: () => 56` — приближённая высота строки (px), для расчёта `totalSize`.
+- `overscan: 5` — сколько строк рендерить за экраном для плавности.
+
+**Динамические высоты:**
+- `measureElement: el => el.getBoundingClientRect().height` + `ref={virtualizer.measureElement}` + `data-index={vRow.index}` на строке.
+
+**Комбо Table + Virtual:** строки берёшь из `table.getRowModel().rows`, виртуализатор работает поверх — `transform: translateY(${vRow.start}px)` на `<tr>`.
+
+➡ Шаблоны: `tanstack-beast-practices-reference` § 6.
+
+---
+
+## См. также
+
+- `tanstack-beast-practices-reference` → готовые код-шаблоны для всех 6 разделов
+- `react-beast-practices` → виртуализация (базовый пример), правила hooks
+- `typescript-beast-practices` → типизация generic запросов и mutation handlers
+- `state-zustand-beast-practices` → граница server state (Query) vs client state (Zustand)
+- `state-rtk-beast-practices` → альтернатива (RTK Query) для того же домена
+- `mongodb-mongoose-best-practices` → backend источник данных для fetcher
+- `node-express-beast-practices` → API endpoints, которые потребляет Query
+- `testing-strategy-js` → тестирование хуков и адаптеров
+- `dev-reference-snippets` → базовые примеры `useQuery` / `useMutation`