@fozy-labs/rx-toolkit 0.5.4 → 0.6.2

package/docs/query/README.md

@@ -1,575 +1,65 @@
-# RxQuery
+# Модуль Query
 
-> **Note:** Экспериментальная версия Query v2 доступна — см. [Query v2](../query-v2/README.md).
+Модуль Query — декларативное управление серверными данными: кеширование, инвалидация, оптимистичные обновления и SSR. Построен на RxJS и [сигналах][signals], не зависит от UI-фреймворка — React-интеграция подключается плагином. Два базовых примитива: [ресурс][resource] (чтение данных с кешем по аргументам) и [команда][command] (мутация / побочное действие).
 
-RxQuery — система для управления асинхронными запросами и кэшированием данных в RxToolkit. Она состоит из двух основных компонентов: **Resources** и **Commands**.
 
-## Основные концепции
-
-### Resources (Ресурсы)
-
-Resources предназначены для реактивного кэширования повторяемых запросов. Они автоматически управляют состоянием загрузки, кэшируют результаты и обеспечивают эффективную инвалидацию данных.
-
-**Ключевые особенности:**
-- Автоматическое кэширование по аргументам запроса
-- Поддержка AbortController для отмены запросов
-- Реактивные обновления состояния
-- Оптимистичные обновления
-- Гибкое управление временем жизни кэша
-
-### Commands (Команды)
-
-Commands представляют одноразовые команды или мутации. Они не кэшируются, но предоставляют состояние выполнения и могут связываться с ресурсами для их обновления.
-
-**Ключевые особенности:**
-- Отслеживание состояния выполнения
-- Связывание с ресурсами для их обновления
-- Поддержка оптимистичных обновлений
-- Возможность блокировки связанных ресурсов
-- Автоматический откат при ошибках
-
-### Agents (Агенты)
-
-Agents представляют собой интеллектуальные обертки над ресурсами (или командами), которые обеспечивают более удобную работу с состояниями запросов для потребителей.
-
-**Основная проблема, которую решают агенты:**
-
-Кэш ресурсов содержит "сырые" состояния отдельных запросов, но потребителям нужна более высокоуровневая логика:
-- `isInitialLoading` должно быть true только при первой загрузке ресурса
-- При смене аргументов запроса нужно показывать данные предыдущего запроса, пока загружается новый
-- Состояние загрузки должно отражать контекст использования, а не просто состояние кэша
-
-### ResourceRef (Ссылка на ресурс)
-
-Ref — это абстракция для взаимодействия с элементом кэша ресурса напрямую.
-
-**Особенности:**
-- Команды используют ref под капотом для управления связанным ресурсом
-- Ref может ссылаться на отсутствующий элемент кэша
-- Позволяет выполнять patch-транзакции для оптимистичных обновлений
-
----
-
-## API
-
-### createResource
-
-Создает новый ресурс для кэширования данных.
-
-```typescript
-import { createResource } from '@fozy-labs/rx-toolkit';
-
-interface User {
-    id: string;
-    name: string;
-    email: string;
-}
-
-const userResource = createResource<{ id: string }, User>({
-    async queryFn(args, tools) {
-        const response = await fetch(`/api/users/${args.id}`, {
-            signal: tools.abortSignal // Поддержка отмены запроса
-        });
-        return response.json();
-    },
-    
-    // Опционально: трансформация данных
-    select: (data) => ({
-        id: data.id,
-        name: data.name,
-        email: data.email
-    }),
-    
-    // Опционально: время жизни кэша (по умолчанию 60 секунд)
-    cacheLifetime: 30000, // 30 секунд
-    
-    // Опционально: имя для devtools
-    devtoolsName: 'user-resource',
-    
-    // Опционально: кастомное сравнение аргументов
-    compareArgsFn: (args1, args2) => args1.id === args2.id,
-});
-```
-
-**Параметры createResource:**
-
-| Параметр | Тип | Описание |
-|----------|-----|----------|
-| `queryFn` | `(args, tools) => Promise<Result>` | Функция выполнения запроса |
-| `select` | `(data) => Selected` | Опциональная функция трансформации данных |
-| `cacheLifetime` | `number \| false` | Время жизни кэша в мс (default: 60000). `false` — кэш не удаляется |
-| `compareArgsFn` | `(args1, args2) => boolean` | Кастомная функция сравнения аргументов |
-| `onCacheEntryAdded` | `(args, tools) => void` | Хук при добавлении элемента в кэш |
-| `onQueryStarted` | `(args, tools) => void` | Хук при старте запроса |
-| `devtoolsName` | `string \| false` | Имя для devtools (`false` — отключить) |
-
-**Tools в queryFn:**
-- `abortSignal` — AbortSignal для отмены запроса
-
-### createCommand
-
-Создает новую команду для выполнения мутаций.
-
-```typescript
-import { createCommand } from '@fozy-labs/rx-toolkit';
-
-const updateUser = createCommand<
-    { id: string; data: Partial<User> },
-    User
->({
-    async queryFn(args) {
-        const response = await fetch(`/api/users/${args.id}`, {
-            method: 'PATCH',
-            headers: { 'Content-Type': 'application/json' },
-            body: JSON.stringify(args.data)
-        });
-        return response.json();
-    },
-    
-    // Связывание с ресурсами
-    link(add) {
-        add({
-            resource: userResource,
-            forwardArgs: (args) => ({ id: args.id }),
-            // Обновление кэша после успешного запроса
-            update({ draft, args, data }) {
-                Object.assign(draft, args.data);
-            },
-        });
-    },
-    
-    devtoolsName: 'update-user',
-});
-```
-
-**Параметры createCommand:**
-
-| Параметр            | Тип                         | Описание                                      |
-|---------------------|-----------------------------|-----------------------------------------------|
-| `queryFn`           | `(args) => Promise<Result>` | Функция выполнения команды                    |
-| `select`            | `(data) => Selected`        | Опциональная функция трансформации результата |
-| `link`              | `(add) => void`             | Функция связывания с ресурсами                |
-| `cacheLifetime`     | `number \| false`           | Время жизни кэша команды (default: 1000)      |
-| `onCacheEntryAdded` | `(args, tools) => void`     | Хук при добавлении в кэш                      |
-| `onQueryStarted`    | `(args, tools) => void`     | Хук при старте команды                        |
-| `devtoolsName`      | `string \| false`           | Имя для devtools                              |
-
-> **Note:** `createOperation` and `useOperationAgent` are deprecated aliases for `createCommand` and `useCommandAgent` respectively. They will be removed in v0.6.0.
-
----
-
-## Свойства Link
-
-Link позволяет связывать команды с ресурсами для автоматического обновления кэша:
+## Быстрый старт
 
 ```typescript
-type LinkOptions<D, RD> = {
-    /**
-     * Целевой ресурс, с которым связывается команда
-     * @required
-     */
-    resource: ResourceInstance<RD>;
-
-    /**
-     * Функция для получения аргументов ресурса из аргументов команды.
-     * Используется для определения какой элемент в кэше нужно обновить
-     * @required
-     */
-    forwardArgs: (args: D["Args"]) => RD["Args"];
-
-    /**
-     * Инвалидация кэша после выполнения команды.
-     * При true — кэш будет очищен и ресурс перезагрузится
-     * @default false
-     */
-    invalidate?: boolean;
+import { createApi, reactHooksPlugin } from '@fozy-labs/rx-toolkit';
 
-    /**
-     * Блокировка ресурса во время выполнения команды.
-     * При true — ресурс не сможет выполнять новые запросы
-     * @default false
-     */
-    lock?: boolean;
+const api = createApi({ plugins: [reactHooksPlugin()] });
 
-    /**
-     * Обновление кэша ПОСЛЕ успешного выполнения команды.
-     * Использует Immer для иммутабельных обновлений
-     */
-    update?: (tools: {
-        draft: RD["Data"];      // Immer draft для мутации
-        args: D["Args"];        // Аргументы команды
-        data: D["Data"];        // Результат команды
-    }) => void | RD["Data"];
-
-    /**
-     * Оптимистичное обновление ДО выполнения команды.
-     * Позволяет обновить UI немедленно
-     */
-    optimisticUpdate?: (tools: {
-        draft: RD["Data"];      // Immer draft для мутации
-        args: D["Args"];        // Аргументы команды
-    }) => void | RD["Data"];
-
-    /**
-     * Создание нового элемента в кэше.
-     * Используется когда команда создает новую сущность
-     */
-    create?: (tools: {
-        args: D["Args"];
-        data: D["Data"];
-    }) => RD["Data"] | Promise<RD["Data"]>;
-};
-```
-
-### Пример: Оптимистичные обновления
-
-```typescript
-const toggleCartItem = createCommand({
-    queryFn: async (args: { id: string; enabled: boolean }) => {
-        return fetch(`/api/cart/toggle`, {
-            method: 'POST',
-            body: JSON.stringify(args)
-        }).then(r => r.json());
-    },
-    link(add) {
-        add({
-            resource: cartResource,
-            forwardArgs: () => undefined, // Корзина без параметров
-            
-            // Оптимистичное обновление — UI обновится мгновенно
-            optimisticUpdate: ({ draft, args }) => {
-                const item = draft.items.find(i => i.id === args.id);
-                if (item) {
-                    item.enabled = args.enabled;
-                }
-            }
-            // При ошибке изменения автоматически откатятся
-        });
-    }
+const usersResource = api.createResource({
+  queryFn: async (args: { page: number }, signal) => {
+    const res = await fetch(`/api/users?page=${args.page}`, { signal });
+    return res.json();
+  },
 });
-```
-
----
 
-## Состояния запросов
-
-### ResourceQueryState
-
-Состояние запроса ресурса через агента:
-
-```typescript
-type ResourceQueryState<D> = {
-    /** Инициализирован ли хотя бы один запрос */
-    isInitiated: boolean;
-    
-    /** Любая загрузка (первая или повторная) */
-    isLoading: boolean;
-    
-    /** Первая загрузка (данных еще не было) */
-    isInitialLoading: boolean;
-    
-    /** Перезагрузка (данные уже есть) */
-    isReloading: boolean;
-    
-    /** Завершен ли запрос */
-    isDone: boolean;
-    
-    /** Успешно ли завершен последний запрос */
-    isSuccess: boolean;
-    
-    /** Произошла ли ошибка последнего запроса */
-    isError: boolean;
-    
-    /** Заблокирован ли ресурс командой */
-    isLocked: boolean;
-    
-    /** Оригинал ошибки, если есть */
-    error: unknown | undefined;
-    
-    /** Данные (или select данных) */
-    data: D["Data"] | undefined;
-    
-    /** Аргументы последнего запроса */
-    args: D["Args"] | undefined;
-}
-```
-
-### CommandQueryState
-
-Состояние выполнения команды:
-
-```typescript
-type CommandQueryState<D> = {
-    isInitiated: boolean;
-    isLoading: boolean;
-    isDone: boolean;
-    isSuccess: boolean;
-    isError: boolean;
-    error: unknown | undefined;
-    data: D["Data"] | undefined;
+// React-компонент
+function UsersList({ page }: { page: number }) {
+  const { data, error, isLoading } = usersResource.useResource({ page });
+  if (isLoading) return <Spinner />;
+  return <ul>{data.map(u => <li key={u.id}>{u.name}</li>)}</ul>;
 }
 ```
 
----
-
-## ResourceRef API
-
-ResourceRef предоставляет низкоуровневый доступ к элементу кэша:
-
-```typescript
-type ResourceRefInstance<D> = {
-    /** Проверка наличия элемента в кэше */
-    get has(): boolean;
-    
-    /** Блокировка ресурса (возвращает функцию разблокировки) */
-    lock(): { unlock: () => void };
-    
-    /** Снятие одной блокировки */
-    unlockOne(): void;
-    
-    /** Patch-транзакция для изменения данных */
-    patch(patchFn: (data: D['Data']) => void): ResourceTransaction | null;
-    
-    /** Инвалидация (очистка) кэша */
-    invalidate(): void;
-    
-    /** Создание элемента в кэше с данными */
-    create(data: D['Data']): void;
-}
-```
-
-### Patch-транзакции
-
-Транзакции позволяют делать изменения с возможностью отката:
-
-```typescript
-type ResourceTransaction = {
-    patches: ImmerPatch[]           // Патчи изменений
-    inversePatches: ImmerPatch[]    // Патчи для отката
-    status: 'pending' | 'committed' | 'aborted'
-    abort(): void                   // Откатить изменения
-    commit(): void                  // Подтвердить изменения
-}
-```
-
-**Пример использования транзакций:**
-
-```typescript
-import { useResourceRef } from '@fozy-labs/rx-toolkit';
-
-function TodoList() {
-    const todoRef = useResourceRef(todoResource, undefined);
-    const [pendingChanges, setPendingChanges] = useState([]);
-    
-    const handleToggle = (itemId: number) => {
-        const transaction = todoRef.patch((draft) => {
-            const item = draft.items.find(i => i.id === itemId);
-            if (item) item.completed = !item.completed;
-        });
-        
-        if (transaction) {
-            setPendingChanges(prev => [...prev, {
-                id: itemId,
-                transaction
-            }]);
-        }
-    };
-    
-    const commitChange = (id: number) => {
-        const change = pendingChanges.find(c => c.id === id);
-        change?.transaction.commit();
-        setPendingChanges(prev => prev.filter(c => c.id !== id));
-    };
-    
-    const abortChange = (id: number) => {
-        const change = pendingChanges.find(c => c.id === id);
-        change?.transaction.abort(); // Данные вернутся к исходным
-        setPendingChanges(prev => prev.filter(c => c.id !== id));
-    };
-}
-```
-
----
-
-## Lifecycle хуки
-
-### onCacheEntryAdded
-
-Вызывается при добавлении нового элемента в кэш:
-
-```typescript
-const userResource = createResource({
-    queryFn: fetchUser,
-    
-    onCacheEntryAdded(args, { $cacheDataLoaded, $cacheEntryRemoved, dataChanged$ }) {
-        // args — аргументы запроса
-        
-        // Ожидание первой загрузки данных
-        $cacheDataLoaded.then(() => {
-            console.log('Данные загружены в кэш');
-        });
-        
-        // Ожидание удаления из кэша
-        $cacheEntryRemoved.then(() => {
-            console.log('Элемент удален из кэша');
-        });
-        
-        // Подписка на изменения данных
-        const sub = dataChanged$.subscribe(data => {
-            console.log('Данные изменились:', data);
-        });
-    }
-});
-```
-
-### onQueryStarted
-
-Вызывается при старте каждого запроса:
-
-```typescript
-const userResource = createResource({
-    queryFn: fetchUser,
-    
-    async onQueryStarted(args, { $queryFulfilled }) {
-        console.log('Запрос начат с аргументами:', args);
-        
-        const result = await $queryFulfilled;
-        
-        if (result.isError) {
-            console.error('Ошибка запроса:', result.error);
-        } else {
-            console.log('Запрос успешен:', result.data);
-        }
-    }
-});
-```
-
----
-
-## Утилиты
-
-### resetAllQueriesCache
-
-Сбрасывает кэш всех ресурсов в приложении:
-
-```typescript
-import { resetAllQueriesCache } from '@fozy-labs/rx-toolkit';
-
-function LogoutButton() {
-    const handleLogout = () => {
-        // Очистить все кэшированные данные при выходе
-        resetAllQueriesCache();
-        navigate('/login');
-    };
-    
-    return <button onClick={handleLogout}>Выйти</button>;
-}
-```
-
-### SKIP токен
-
-Используется для условного пропуска запроса:
-
-```typescript
-import { useResourceAgent, SKIP } from '@fozy-labs/rx-toolkit';
-
-function UserProfile({ userId }: { userId: string | null }) {
-    // Запрос будет выполнен только если userId не null
-    const userQuery = useResourceAgent(
-        userResource,
-        userId ? { id: userId } : SKIP
-    );
-    
-    if (!userId) return <div>Выберите пользователя</div>;
-    if (userQuery.isLoading) return <div>Загрузка...</div>;
-    
-    return <div>{userQuery.data?.name}</div>;
-}
-```
-
----
-
-## Примеры
-
-### Корзина покупок с оптимистичными обновлениями
-
-```typescript
-import { createResource, createCommand, useResourceAgent, useCommandAgent } from '@fozy-labs/rx-toolkit';
-
-const cartResource = createResource({
-    queryFn: () => fetch('/api/cart').then(r => r.json()),
-    devtoolsName: 'cart'
-});
-
-const toggleCartItem = createCommand({
-    queryFn: (args: { id: string; enabled: boolean }) => 
-        fetch('/api/cart/toggle', {
-            method: 'POST',
-            body: JSON.stringify(args)
-        }).then(r => r.json()),
-    
-    link(add) {
-        add({
-            resource: cartResource,
-            forwardArgs: () => undefined,
-            optimisticUpdate: ({ draft, args }) => {
-                const item = draft.items.find(i => i.id === args.id);
-                if (item) item.enabled = args.enabled;
-            }
-        });
-    }
-});
-
-function ShoppingCart() {
-    const cartQuery = useResourceAgent(cartResource, undefined);
-    const [toggleItem, toggleState] = useCommandAgent(toggleCartItem);
-    
-    return (
-        <div>
-            {cartQuery.data?.items.map(item => (
-                <div key={item.id}>
-                    <span>{item.name}</span>
-                    <button onClick={() => toggleItem({ 
-                        id: item.id, 
-                        enabled: !item.enabled 
-                    })}>
-                        {item.enabled ? 'Убрать' : 'Добавить'}
-                    </button>
-                </div>
-            ))}
-        </div>
-    );
-}
-```
-
-### Зависимые запросы
-
-```typescript
-const userResource = createResource({
-    queryFn: (args: { id: number }) => fetch(`/api/users/${args.id}`).then(r => r.json()),
-});
-
-const userStatsResource = createResource({
-    queryFn: (args: { userId: number; period: string }) => 
-        fetch(`/api/users/${args.userId}/stats?period=${args.period}`).then(r => r.json()),
-});
-
-function UserDashboard({ userId }: { userId: number }) {
-    const [period, setPeriod] = useState('daily');
-    
-    const userQuery = useResourceAgent(userResource, { id: userId });
-    
-    // Запрос статистики выполняется только после загрузки пользователя
-    const statsQuery = useResourceAgent(
-        userStatsResource,
-        userQuery.isSuccess ? { userId, period } : SKIP
-    );
-    
-    // ...
-}
-```
-
-## React интеграция
-
-См. [React интеграция](../usage/react/README.md) для подробной информации о React хуках.
 
+## Возможности
+
+- **Кеширование** — автоматическое по аргументам, с настраиваемым временем жизни
+- **Stale-While-Revalidate** — показ устаревших данных во время фонового обновления
+- **Оптимистичные обновления** — Immer-патчи с автоматическим ребейсом при ответе сервера
+- **SSR / гидрация** — снимки кеша для серверного рендеринга
+- **Кросс-табовая синхронизация** — BroadcastChannel для актуальности данных между вкладками
+- **Система плагинов** — расширение ресурсов и команд через `createApi({ plugins: [...] })`
+
+
+## Что читать дальше
+
+| Цель | Рекомендуемый порядок |
+|------|-----------------------|
+| **Быстрый старт** | [usage/resource.md][resource] → [usage/command.md][command] |
+| **Понять внутреннее устройство** | [concepts/machine.md][machine] → [concepts/cache.md][cache] → [concepts/agent.md][agent] |
+| **Оптимистичные обновления** | [concepts/patching.md][patching] → [usage/links.md][links] |
+| **SSR / гидрация** | [usage/snapshot.md][snapshot] |
+| **Кросс-табовая синхронизация** | [usage/broadcast.md][broadcast] |
+| **API-справочник** | [api/README.md][api] → [api/resource.md][api-resource] → [api/command.md][api-command] |
+| **Написание плагинов** | [usage/plugins.md][plugins] |
+
+
+[signals]: ../signals/README.md
+[resource]: usage/resource.md
+[command]: usage/command.md
+[machine]: concepts/machine.md
+[cache]: concepts/cache.md
+[agent]: concepts/agent.md
+[patching]: concepts/patching.md
+[links]: usage/links.md
+[snapshot]: usage/snapshot.md
+[broadcast]: usage/broadcast.md
+[api]: api/README.md
+[api-resource]: api/resource.md
+[api-command]: api/command.md
+[plugins]: usage/plugins.md

package/docs/query/api/README.md

@@ -0,0 +1,59 @@
+# RxQuery API
+
+API — центральный объект, управляющий ресурсами и командами.
+
+
+## Создание API
+
+```typescript
+import { createApi, reactHooksPlugin } from '@fozy-labs/rx-toolkit';
+
+const api = createApi({
+    keyPrefix: 'my-app', // (опционально) префикс для всех ключей ресурсов
+    plugins: [
+        reactHooksPlugin(), // (опционально) подключаем React Hooks плагин для удобного использования в React-приложениях
+    ],
+});
+```
+
+
+## Опции API
+
+| Опция                | Тип                       | По умолчанию      | Описание                                                                                                                        |
+|----------------------|---------------------------|-------------------|---------------------------------------------------------------------------------------------------------------------------------|
+| `keyPrefix`          | `string` \| `null`        | `undefined`       | Префикс, который добавляется ко всем ключам ресурсов и команд, создаваемых через этот API.                                      |
+| `plugins`            | `IPlugin[]`               | `[]`              | Массив плагинов, которые будут использоваться этим API.                                                                         |
+| `serializeArgs`      | `(args: TArgs) => string` | `stableStringify` | Функция сериализации аргументов в строку.                                                                                       |
+| `resourceRetentionTime` | `number` \| `false`       | `60_000 ms`       | Время удержания кэша ресурсов. `false` — не удалять.                                            |
+| `commandRetentionTime`  | `number` \| `false`       | `0`               | Время удержания кэша команд. `false` — не удалять.                                              |
+| `initialSnapshot`    | `TApiSnapshot` \| `null`  | `null`            | Начальный [снимок] состояния всех ресурсов (для SSR или гидрации).                                                              |
+| `snapshotValidTime`  | `number` \| `false`       | `false`           | Время валидности данных в снимке. `false` - данные в [снимке][снимок] считаются всегда валидными.                               |
+| `defaultSync`        | `'none'` \| `'resources'` \| `'all'` | `'none'`          | Режим синхронизации по умолчанию для ресурсов. `'none'` — выключена, `'resources'` / `'all'` — включена. Команды не поддерживают синхронизацию. |
+| `syncDriver`         | `ISyncDriver`             | `undefined`       | Драйвер для [синхронизации][синхронизация] состояния между несколькими экземплярами API (например, в разных вкладках браузера). |
+| `onCacheEntryAdded`  | `(args, ctx) => void`     | —                 | Хук жизненного цикла уровня API — вызывается при создании любой кэш-записи. См. [lifecycle hooks][lifecycle].                  |
+| `onQueryStarted`     | `(args, ctx) => void \| Promise<void>` | — | Хук жизненного цикла уровня API — вызывается при каждом запуске `queryFn`. См. [lifecycle hooks][lifecycle].                    |
+
+## Методы API
+
+| Метод            | Опции                                      | Возвращаемое значение                  | Описание                                                        |
+|------------------|--------------------------------------------|-----------------------------------------|-----------------------------------------------------------------|
+| `createResource` | `options: TResourceOptions<TArgs, TData>`  | `IApiResource<TPlugins, TArgs, TData>`  | Создаёт новый [ресурс].                                        |
+| `createCommand`  | `options: TCommandOptions<TArgs, TData>`   | `IApiCommand<TPlugins, TArgs, TData>`   | Создаёт новую [команду][команда].                               |
+| `getSnapshot()`  | -                                          | `TApiSnapshot`                          | Получает текущий [снимок] состояния всех [ресурсов][ресурс].    |
+| `resetAll()`     | -                                          | `void`                                  | Сбрасывает все ресурсы и очищает сохранённый снимок.            |
+
+
+## См. также
+
+- [Ресурс](../usage/resource.md)
+- [Команда](../usage/command.md)
+- [Снимок (SSR / гидрация)](../usage/snapshot.md)
+- [Синхронизация между вкладками](../usage/broadcast.md)
+- [Lifecycle hooks](../usage/lifecycle.md)
+
+
+[снимок]: ../usage/snapshot.md
+[синхронизация]: ../usage/broadcast.md
+[lifecycle]: ../usage/lifecycle.md
+[ресурс]: ../usage/resource.md
+[команда]: ../usage/command.md