@fozy-labs/rx-toolkit 0.5.3-rc.2 → 0.5.4

package/docs/query-v2/README.md

@@ -0,0 +1,280 @@
+# RxQuery v2 (**experimental**)
+
+> ⚠️ **Экспериментальный модуль.** API может измениться без предупреждения. Используйте с осторожностью в production.
+
+RxQuery v2 — переработанная система управления асинхронными запросами и кэшированием данных в RxToolkit. В отличие от v1, v2 строится вокруг единой фабрики `createApi`, machine-based состояний и плагинной архитектуры.
+
+## Основные концепции
+
+### createApi
+
+Точка входа для создания API-инстанса. Все ресурсы создаются через API, что обеспечивает общую конфигурацию, snapshot-поддержку и плагины.
+
+```typescript
+import { unstable_queryV2 } from '@fozy-labs/rx-toolkit';
+
+const api = unstable_queryV2.createApi({
+    keyPrefix: 'my-app',
+    cacheLifetime: 60_000,
+    plugins: [new unstable_queryV2.ReactHooksPlugin()],
+});
+```
+
+**Параметры:**
+
+| Параметр | Тип | По умолчанию | Описание |
+|----------|-----|-------------|----------|
+| `keyPrefix` | `string \| null` | `null` | Префикс ключей для namespace-изоляции |
+| `keyStrategy` | `'serialize' \| 'compare'` | `'serialize'` | Стратегия ключей кэша |
+| `serializeArgs` | `(args) => string` | — | Кастомная сериализация аргументов |
+| `compareArg` | `(a, b) => boolean` | — | Кастомное сравнение аргументов |
+| `cacheLifetime` | `number` | `60000` | Время жизни кэша (мс) |
+| `plugins` | `IPlugin[]` | `[]` | Массив плагинов |
+| `initialSnapshot` | `TApiSnapshot \| null` | `null` | Начальный snapshot для SSR-гидрации |
+| `maxSnapshotDataAge` | `number` | `300000` | Максимальный возраст данных snapshot (мс) |
+| `doCacheArgs` | `boolean` | `false` | Кэшировать ли аргументы в кэш-записи |
+
+### ResourceV2
+
+Ресурс — единица кэширования. Создаётся через `api.createResource()`. В отличие от v1, ресурс всегда принадлежит API-инстансу.
+
+```typescript
+interface User {
+    id: string;
+    name: string;
+}
+
+const userResource = api.createResource<{ id: string }, User>({
+    key: 'users',
+    queryFn: async (args, { abortSignal }) => {
+        const res = await fetch(`/api/users/${args.id}`, { signal: abortSignal });
+        return res.json();
+    },
+    cacheLifetime: 30_000,
+});
+```
+
+**Параметры `createResource`:**
+
+| Параметр | Тип | Описание |
+|----------|-----|----------|
+| `key` | `string` | Уникальный ключ ресурса (обязателен для SSR) |
+| `queryFn` | `(args, tools) => Promise<TData>` | Функция запроса |
+| `cacheLifetime` | `number` | Время жизни кэша (переопределяет API-уровень) |
+| `serializeArgs` | `(args) => string` | Кастомная сериализация (переопределяет API-уровень) |
+| `compareArg` | `(a, b) => boolean` | Кастомное сравнение (переопределяет API-уровень) |
+| `onCacheEntryAdded` | `(args, tools) => void` | Хук при добавлении записи в кэш |
+| `onQueryStarted` | `(args, tools) => void` | Хук при старте запроса |
+| `beforeDevtoolsPush` | `(value, push) => void` | Перехват состояния перед отправкой в devtools |
+| `maxSnapshotDataAge` | `number` | Возраст данных для snapshot |
+| `doCacheArgs` | `boolean` | Кэшировать ли аргументы |
+
+### Agents (Агенты)
+
+Agent — наблюдатель за ресурсом с поддержкой stale-while-revalidate. Предоставляет вычисляемое состояние с удобными флагами.
+
+```typescript
+const agent = userResource.createAgent();
+agent.start({ id: '1' });
+
+// Реактивное состояние
+const state = agent.state$();
+console.log(state.status);      // 'pending' | 'success' | ...
+console.log(state.data);        // TData | null
+console.log(state.isLoading);   // true/false
+```
+
+**Состояние агента (`IResourceV2AgentState`):**
+
+| Поле | Тип | Описание |
+|------|-----|----------|
+| `status` | `TMachineStatus` | Текущий статус машины |
+| `data` | `TData \| null` | Текущие данные (могут быть устаревшими при обновлении) |
+| `error` | `TError \| null` | Текущая ошибка |
+| `args` | `TArgs \| null` | Текущие аргументы |
+| `isLoading` | `boolean` | Индикатор загрузки |
+| `isInitialLoading` | `boolean` | `true` только при первой загрузке (нет предыдущих данных) |
+| `isRefreshing` | `boolean` | `true` при обновлении существующих данных |
+| `isSuccess` | `boolean` | `true` когда данные доступны |
+| `isError` | `boolean` | `true` при ошибке |
+| `refreshError` | `TError \| null` | Ошибка фонового обновления (устаревшие данные сохранены) |
+
+### Machine States (Машина состояний)
+
+В v2 состояние кэш-записи описывается машиной состояний вместо набора boolean-флагов:
+
+| Состояние | Описание | Данные |
+|-----------|----------|--------|
+| `idle` | Начальное состояние | — |
+| `pending` | Первый запрос выполняется | — |
+| `success` | Данные загружены | ✅ |
+| `error` | Запрос завершился с ошибкой | — |
+| `refreshing` | Обновление при наличии данных | ✅ (устаревшие) |
+
+Классы машин: `MachineIdle`, `MachinePending`, `MachineSuccess`, `MachineError`, `MachineRefreshing`.
+
+### Cache Strategies (Стратегии кэша)
+
+Доступны две стратегии определения ключей кэша:
+
+- **`serialize`** (по умолчанию) — аргументы сериализуются в строку (поддерживает SSR snapshots)
+- **`compare`** — аргументы сравниваются функцией (не поддерживает snapshots)
+
+### SKIP_TOKEN
+
+Специальный токен для пропуска запроса (полезен при условных запросах).
+
+```typescript
+import { unstable_queryV2 } from '@fozy-labs/rx-toolkit';
+
+const { SKIP } = unstable_queryV2;
+
+// В React с плагином
+const state = userResource.useResourceV2Agent(
+    userId ? { id: userId } : SKIP,
+);
+```
+
+### Lifecycle Hooks (Хуки жизненного цикла)
+
+#### onCacheEntryAdded
+
+Вызывается при создании новой записи кэша. Полезен для WebSocket-подписок.
+
+```typescript
+const resource = api.createResource({
+    key: 'messages',
+    queryFn: fetchMessages,
+    onCacheEntryAdded: async (args, { $cacheDataLoaded, $cacheEntryRemoved }) => {
+        await $cacheDataLoaded;
+        const ws = new WebSocket(`/ws/messages/${args.channelId}`);
+        await $cacheEntryRemoved;
+        ws.close();
+    },
+});
+```
+
+**Tools (onCacheEntryAdded):**
+
+| Поле | Тип | Описание |
+|------|-----|----------|
+| `$cacheDataLoaded` | `Promise<TData>` | Разрешается при первом `MachineSuccess` |
+| `$cacheEntryRemoved` | `Promise<void>` | Разрешается при удалении записи из кэша |
+| `getCacheEntry()` | `() => TMachine` | Текущее состояние машины |
+
+#### onQueryStarted
+
+Вызывается при каждом старте запроса. Полезен для оптимистичных обновлений.
+
+```typescript
+const resource = api.createResource({
+    key: 'todos',
+    queryFn: updateTodo,
+    onQueryStarted: async (args, { $queryFulfilled, getCacheEntry }) => {
+        // Оптимистичное обновление
+        const entry = getCacheEntry();
+        // ...
+        try {
+            await $queryFulfilled;
+        } catch {
+            // Откат
+        }
+    },
+});
+```
+
+**Tools (onQueryStarted):**
+
+| Поле | Тип | Описание |
+|------|-----|----------|
+| `$queryFulfilled` | `Promise<{ data, isError }>` | Разрешается/отклоняется при завершении запроса |
+| `getCacheEntry()` | `() => ICacheEntry` | Текущая запись кэша для патчинга |
+
+### Plugins (Плагины)
+
+Плагинная архитектура позволяет расширять ресурсы дополнительными методами.
+
+#### ReactHooksPlugin
+
+Добавляет React-хуки к ресурсам:
+
+```typescript
+const api = unstable_queryV2.createApi({
+    plugins: [new unstable_queryV2.ReactHooksPlugin()],
+});
+
+const userResource = api.createResource({ /* ... */ });
+
+// Теперь доступны хуки:
+function UserProfile({ userId }: { userId: string }) {
+    const state = userResource.useResourceV2Agent({ id: userId });
+    const ref = userResource.useResourceV2Ref({ id: userId });
+
+    if (state.isLoading) return <div>Загрузка...</div>;
+    if (state.isError) return <div>Ошибка</div>;
+
+    return <div>{state.data?.name}</div>;
+}
+```
+
+**Методы, добавляемые плагином:**
+
+| Метод | Описание |
+|-------|----------|
+| `useResourceV2Agent(args)` | React-хук агента (реактивное состояние) |
+| `useResourceV2Ref(args)` | React-хук ref (императивный доступ к кэш-записи) |
+
+### ResourceV2Ref (Ссылка на ресурс)
+
+Ref предоставляет императивный доступ к конкретной записи кэша.
+
+| Метод | Описание |
+|-------|----------|
+| `has` | Проверить наличие записи в кэше |
+| `lock()` | Заблокировать запись (предотвратить удаление) |
+| `invalidate()` | Инвалидировать (принудительный перезапрос) |
+| `createPatch(fn)` | Создать оптимистичный патч |
+| `create(data)` | Предзаполнить кэш данными |
+
+---
+
+## Быстрый старт
+
+```typescript
+import { unstable_queryV2 } from '@fozy-labs/rx-toolkit';
+
+// 1. Создаём API
+const api = unstable_queryV2.createApi({
+    plugins: [new unstable_queryV2.ReactHooksPlugin()],
+});
+
+// 2. Создаём ресурс
+const todoResource = api.createResource<void, { items: string[] }>({
+    key: 'todos',
+    queryFn: async (_args, { abortSignal }) => {
+        const res = await fetch('/api/todos', { signal: abortSignal });
+        return res.json();
+    },
+});
+
+// 3. Используем в React
+function TodoList() {
+    const { data, isLoading, isError } = todoResource.useResourceV2Agent(undefined);
+
+    if (isLoading) return <div>Загрузка...</div>;
+    if (isError) return <div>Ошибка</div>;
+
+    return (
+        <ul>
+            {data?.items.map((item, i) => <li key={i}>{item}</li>)}
+        </ul>
+    );
+}
+```
+
+## Дополнительные материалы
+
+- [API Reference](./api-reference.md) — полная таблица типов и параметров
+- [Оптимистичные обновления](./optimistic-updates.md) — гайд по патчам
+- [SSR](./ssr.md) — серверный рендеринг и snapshots
+- [Миграция с v1](../migrations/query-v2.md) — гайд по миграции

package/docs/query-v2/api-reference.md

@@ -0,0 +1,235 @@
+# API Reference — RxQuery v2
+
+> ⚠️ **Экспериментальный модуль.** API может измениться.
+
+## createApi
+
+Фабрика для создания API-инстанса.
+
+```typescript
+function createApi<TPlugins extends IPlugin[] = []>(
+    options?: ICreateApiOptions<TPlugins>,
+): IApi<TPlugins>;
+```
+
+### ICreateApiOptions
+
+| Параметр | Тип | По умолчанию | Описание |
+|----------|-----|-------------|----------|
+| `keyPrefix` | `string \| null` | `null` | Префикс ключей для namespace-изоляции |
+| `keyStrategy` | `'serialize' \| 'compare'` | `'serialize'` | Стратегия ключей кэша |
+| `serializeArgs` | `TSerializeArgsFn` | — | Кастомная сериализация аргументов |
+| `compareArg` | `TCompareArgsFn` | — | Кастомное сравнение аргументов |
+| `cacheLifetime` | `number` | `60000` | Время жизни кэша (мс) |
+| `plugins` | `IPlugin[]` | `[]` | Массив плагинов |
+| `initialSnapshot` | `TApiSnapshot \| null` | `null` | Начальный snapshot (SSR) |
+| `maxSnapshotDataAge` | `number` | `300000` | Макс. возраст snapshot-данных (мс) |
+| `doCacheArgs` | `boolean` | `false` | Кэшировать ли аргументы в кэш-записи |
+
+### IApi
+
+| Метод | Сигнатура | Описание |
+|-------|-----------|----------|
+| `createResource` | `<TArgs, TData, TError>(options: IResourceV2Options) => IResourceV2 & PluginAugmentations` | Создать ресурс |
+| `resetAll` | `() => void` | Сбросить все ресурсы |
+| `getSnapshot` | `() => TApiSnapshot` | Получить snapshot для SSR |
+
+---
+
+## api.createResource
+
+Создаёт ресурс, привязанный к API-инстансу.
+
+### IResourceV2Options
+
+| Параметр | Тип | Описание |
+|----------|-----|----------|
+| `key` | `string` | Уникальный ключ ресурса (обязателен для SSR snapshots) |
+| `queryFn` | `(args: TArgs, tools: TQueryFnTools) => Promise<TData>` | Функция запроса |
+| `cacheLifetime` | `number` | Время жизни кэша (мс), переопределяет API-уровень |
+| `serializeArgs` | `TSerializeArgsFn` | Кастомная сериализация (переопределяет API-уровень) |
+| `compareArg` | `TCompareArgsFn` | Кастомное сравнение (переопределяет API-уровень) |
+| `onCacheEntryAdded` | `TOnCacheEntryAdded<TArgs, TData>` | Хук при добавлении записи в кэш |
+| `onQueryStarted` | `TOnQueryStarted<TArgs, TData>` | Хук при старте запроса |
+| `beforeDevtoolsPush` | `TBeforeDevtoolsPushFn` | Перехват перед devtools |
+| `maxSnapshotDataAge` | `number` | Возраст данных для snapshot (мс) |
+| `doCacheArgs` | `boolean` | Кэшировать ли аргументы |
+
+### TQueryFnTools
+
+| Поле | Тип | Описание |
+|------|-----|----------|
+| `abortSignal` | `AbortSignal` | Сигнал для отмены запроса |
+
+---
+
+## IResourceV2
+
+Интерфейс ресурса (публичный API).
+
+| Метод | Сигнатура | Описание |
+|-------|-----------|----------|
+| `createAgent` | `() => IResourceV2Agent` | Создать агента (observer + SWR) |
+| `query` | `(args, doForce?) => Promise<ICacheEntry>` | Выполнить запрос |
+| `query$` | `(args, doForce?) => TMachine` | Реактивный запрос (signal read) |
+| `entry` | `(args, doInitiate?) => ICacheEntry \| null` | Получить запись кэша (нереактивно) |
+| `entry$` | `(args, doInitiate?) => TMachine` | Получить запись кэша (реактивно) |
+| `invalidate` | `(args) => void` | Инвалидировать запись |
+| `compareArgs` | `(a, b) => boolean` | Сравнить аргументы |
+
+---
+
+## IResourceV2Agent
+
+Агент — наблюдатель за ресурсом с stale-while-revalidate.
+
+| Поле/Метод | Сигнатура | Описание |
+|------------|-----------|----------|
+| `state$` | `() => IResourceV2AgentState` | Реактивное состояние (computed signal) |
+| `start` | `(args: TArgs \| SKIP_TOKEN) => Promise<void>` | Начать запрос с новыми аргументами |
+| `compareArgs` | `(a, b) => boolean` | Сравнить аргументы |
+
+### IResourceV2AgentState
+
+| Поле | Тип | Описание |
+|------|-----|----------|
+| `status` | `TMachineStatus` | Текущий статус: `'idle'` \| `'pending'` \| `'success'` \| `'error'` \| `'refreshing'` |
+| `data` | `TData \| null` | Текущие данные |
+| `error` | `TError \| null` | Текущая ошибка |
+| `args` | `TArgs \| null` | Текущие аргументы |
+| `isLoading` | `boolean` | Загрузка (pending или refreshing) |
+| `isInitialLoading` | `boolean` | Первая загрузка (нет предыдущих данных) |
+| `isRefreshing` | `boolean` | Обновление существующих данных |
+| `isSuccess` | `boolean` | Данные доступны |
+| `isError` | `boolean` | Ошибка |
+| `refreshError` | `TError \| null` | Ошибка фонового обновления |
+
+---
+
+## IResourceV2Ref
+
+Императивный доступ к записи кэша.
+
+| Поле/Метод | Сигнатура | Описание |
+|------------|-----------|----------|
+| `has` | `boolean` (readonly) | Наличие записи в кэше |
+| `lock` | `() => { unlock: () => void }` | Заблокировать запись |
+| `invalidate` | `() => void` | Инвалидировать |
+| `createPatch` | `(patchFn: TPatchFn<TData>) => { commit, abort } \| null` | Создать оптимистичный патч |
+| `create` | `(data: TData) => void` | Предзаполнить кэш |
+
+---
+
+## Machine Classes
+
+Классы машины состояний, определяющие текущее состояние кэш-записи.
+
+| Класс | Статус | Данные | Ошибка | Описание |
+|-------|--------|--------|--------|----------|
+| `MachineIdle` | `'idle'` | `null` | `null` | Начальное состояние |
+| `MachinePending` | `'pending'` | `null` | `null` | Запрос выполняется |
+| `MachineSuccess` | `'success'` | `TData` | `null` | Данные загружены |
+| `MachineError` | `'error'` | `null` | `TError` | Ошибка запроса |
+| `MachineRefreshing` | `'refreshing'` | `TData` | `null` | Обновление с данными |
+
+### TMachineStatus
+
+```typescript
+type TMachineStatus = 'idle' | 'pending' | 'success' | 'error' | 'refreshing';
+```
+
+---
+
+## Lifecycle Hooks
+
+### TOnCacheEntryAdded
+
+```typescript
+type TOnCacheEntryAdded<TArgs, TData> = (
+    args: TArgs,
+    tools: TCacheEntryAddedTools<TData>,
+) => void | Promise<void>;
+```
+
+#### TCacheEntryAddedTools
+
+| Поле | Тип | Описание |
+|------|-----|----------|
+| `$cacheDataLoaded` | `Promise<TData>` | Разрешается при первом `MachineSuccess` |
+| `$cacheEntryRemoved` | `Promise<void>` | Разрешается при удалении записи |
+| `getCacheEntry` | `() => TMachine` | Текущее состояние машины |
+
+### TOnQueryStarted
+
+```typescript
+type TOnQueryStarted<TArgs, TData> = (
+    args: TArgs,
+    tools: TQueryStartedTools<TData>,
+) => void | Promise<void>;
+```
+
+#### TQueryStartedTools
+
+| Поле | Тип | Описание |
+|------|-----|----------|
+| `$queryFulfilled` | `Promise<{ data: TData; isError: false }>` | Разрешается при завершении запроса |
+| `getCacheEntry` | `() => ICacheEntry` | Запись кэша для патчинга |
+
+---
+
+## Plugins
+
+### IPlugin
+
+```typescript
+interface IPlugin {
+    readonly name: string;
+    install(context: IPluginContext): void;
+    augmentResource<TArgs, TData, TError>(
+        resource: IResourceV2<TArgs, TData, TError>,
+        options: IResourceV2Options<TArgs, TData, TError>,
+    ): Record<string, unknown>;
+}
+```
+
+### ReactHooksPlugin
+
+Добавляет React-хуки к ресурсам:
+
+| Метод | Сигнатура | Описание |
+|-------|-----------|----------|
+| `useResourceV2Agent` | `(args: TArgs \| SKIP_TOKEN) => IResourceV2AgentState` | React-хук агента |
+| `useResourceV2Ref` | `(args: TArgs \| SKIP_TOKEN) => IResourceV2Ref` | React-хук ref |
+
+> **Standalone-импорт:** Хуки `useResourceV2Agent` и `useResourceV2Ref` доступны как отдельные функции без `ReactHooksPlugin`:
+> ```typescript
+> import { useResourceV2Agent } from '@fozy-labs/rx-toolkit/query-v2/react';
+> const state = useResourceV2Agent(resource, args);
+> ```
+
+---
+
+## Snapshot Types
+
+### TApiSnapshot
+
+| Поле | Тип | Описание |
+|------|-----|----------|
+| `version` | `number` | Версия формата |
+| `keyPrefix` | `string \| null` | Префикс ключей API |
+| `resources` | `Record<string, TResourceSnapshot>` | Snapshots ресурсов |
+
+### TResourceSnapshot
+
+| Поле | Тип | Описание |
+|------|-----|----------|
+| `entries` | `Record<string, TResourceV2SnapshotSlice>` | Записи кэша |
+
+### TResourceV2SnapshotSlice
+
+| Поле | Тип | Описание |
+|------|-----|----------|
+| `status` | `'success'` | Всегда success (только успешные записи) |
+| `args` | `unknown` | Аргументы запроса |
+| `data` | `TData` | Данные |
+| `updatedAt` | `number` | Timestamp обновления |

package/docs/query-v2/optimistic-updates.md

@@ -0,0 +1,148 @@
+# Оптимистичные обновления — RxQuery v2
+
+> ⚠️ **Экспериментальный модуль.** API может измениться.
+
+Оптимистичные обновления позволяют мгновенно отобразить результат действия пользователя, не дожидаясь ответа сервера. В v2 это реализуется через механизм патчей (`createPatch` / `finishPatch`).
+
+## Основы
+
+В RxQuery v2 каждая запись кэша поддерживает **очередь патчей** — Immer-based мутаций, которые накладываются поверх оригинальных данных. Патч можно подтвердить (`commit`) или откатить (`abort`).
+
+## Использование через Ref
+
+Самый прямой способ — использовать `IResourceV2Ref`:
+
+```typescript
+import { unstable_queryV2 } from '@fozy-labs/rx-toolkit';
+
+const api = unstable_queryV2.createApi({
+    plugins: [new unstable_queryV2.ReactHooksPlugin()],
+});
+
+interface Todo {
+    id: number;
+    text: string;
+    completed: boolean;
+}
+
+const todosResource = api.createResource<void, { items: Todo[] }>({
+    key: 'todos',
+    queryFn: async (_args, { abortSignal }) => {
+        const res = await fetch('/api/todos', { signal: abortSignal });
+        return res.json();
+    },
+});
+```
+
+### createPatch
+
+Создаёт оптимистичный патч. Принимает функцию-рецепт Immer — мутации `draft` применяются мгновенно к отображаемым данным.
+
+```typescript
+function ToggleTodo({ todo }: { todo: Todo }) {
+    const ref = todosResource.useResourceV2Ref(undefined);
+
+    const handleToggle = async () => {
+        // 1. Создаём оптимистичный патч
+        const patch = ref.createPatch((draft) => {
+            const item = draft.items.find(i => i.id === todo.id);
+            if (item) item.completed = !item.completed;
+        });
+        if (!patch) return;
+
+        try {
+            // 2. Отправляем на сервер
+            await fetch(`/api/todos/${todo.id}`, {
+                method: 'PATCH',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ completed: !todo.completed }),
+            });
+
+            // 3. Подтверждаем патч (данные остаются)
+            patch.commit();
+        } catch {
+            // 4. Откатываем при ошибке (данные возвращаются к оригиналу)
+            patch.abort();
+        }
+    };
+
+    return <button onClick={handleToggle}>{todo.text}</button>;
+}
+```
+
+### Жизненный цикл патча
+
+1. **`createPatch(fn)`** — применяет Immer-рецепт к данным. UI мгновенно обновляется.
+2. **`commit()`** — подтверждает патч. Оригинальные данные обновляются.
+3. **`abort()`** — откатывает патч. Данные возвращаются к предыдущему состоянию.
+
+### Несколько патчей
+
+Патчи накладываются в порядке создания. Каждый патч можно подтвердить или откатить независимо:
+
+```typescript
+const patch1 = ref.createPatch(draft => { draft.items[0].text = 'Изменено 1'; });
+const patch2 = ref.createPatch(draft => { draft.items[1].text = 'Изменено 2'; });
+
+// Подтвердить первый, откатить второй
+patch1?.commit();
+patch2?.abort();
+```
+
+### Патч при отсутствии данных
+
+Если запись кэша не содержит данных (статус не `success` / `refreshing`), `createPatch` вернёт `null`:
+
+```typescript
+const patch = ref.createPatch(draft => { /* ... */ });
+if (!patch) {
+    console.warn('Нет данных для патча');
+    return;
+}
+```
+
+## Паттерн: оптимистичное обновление в компоненте
+
+```tsx
+function TodoList() {
+    const state = todosResource.useResourceV2Agent(undefined);
+    const ref = todosResource.useResourceV2Ref(undefined);
+
+    const toggleTodo = async (todo: Todo) => {
+        const patch = ref.createPatch((draft) => {
+            const item = draft.items.find(i => i.id === todo.id);
+            if (item) item.completed = !item.completed;
+        });
+        if (!patch) return;
+
+        try {
+            await updateTodoOnServer(todo.id, { completed: !todo.completed });
+            patch.commit();
+        } catch {
+            patch.abort();
+        }
+    };
+
+    if (state.isLoading) return <div>Загрузка...</div>;
+    if (!state.data) return null;
+
+    return (
+        <ul>
+            {state.data.items.map(todo => (
+                <li key={todo.id} onClick={() => toggleTodo(todo)}>
+                    {todo.completed ? '✅' : '⬜'} {todo.text}
+                </li>
+            ))}
+        </ul>
+    );
+}
+```
+
+## Сравнение с v1
+
+| Аспект | v1 | v2 |
+|--------|----|----|
+| Механизм | `resourceRef.patch()` + Command link | `ref.createPatch()` → `commit/abort` |
+| Привязка | Через `link()` в Command | Напрямую через Ref |
+| Отмена | Автоматическая через Command | Явный `abort()` |
+| Множественные патчи | Не поддерживаются | Очередь патчей |