@fozy-labs/rx-toolkit 0.5.3-rc.1 → 0.5.3

package/docs/usage/react/README.md

@@ -1,307 +1,309 @@
-# React интеграция
-
-RxToolkit предоставляет набор React хуков для эффективной интеграции с реактивными системами библиотеки. Все хуки оптимизированы для минимальных ре-рендеров и максимальной производительности.
-
-## Основные хуки
-
-### useSignal
-
-Подписывается на изменения сигнала и возвращает текущее значение.
-
-```tsx
-import { Signal, Computed, useSignal } from '@fozy-labs/rx-toolkit';
-
-const counter$ = Signal.create(0);
-const doubled$ = Signal.compute(() => counter$() * 2);
-
-function Counter() {
-    const count = useSignal(counter$);
-    const doubled = useSignal(doubled$);
-
-    return (
-        <div>
-            <p>Count: {count}</p>
-            <p>Doubled: {doubled}</p>
-            <button onClick={() => counter$.set(counter$.peek() + 1)}>
-                Increment
-            </button>
-        </div>
-    );
-}
-```
-
-**Особенности:**
-- Автоматическая подписка и отписка при размонтировании
-- Не вызывает ре-рендер, если значение не изменилось
-
----
-
-## RxQuery хуки
-
-### useResourceAgent
-
-Подписывается на состояние ресурса и автоматически инициирует запрос при монтировании или изменении аргументов.
-
-```tsx
-import { useResourceAgent, SKIP } from '@fozy-labs/rx-toolkit';
-import { userResource } from '../api/userResource';
-
-function UserProfile({ userId }: { userId: string | null }) {
-    const userQuery = useResourceAgent(
-        userResource, 
-        userId ? { id: userId } : SKIP
-    );
-
-    if (userQuery.isInitialLoading) {
-        return <div>Загрузка...</div>;
-    }
-    
-    if (userQuery.isError) {
-        return <div>Ошибка: {String(userQuery.error)}</div>;
-    }
-    
-    if (userQuery.isReloading) {
-        // Показываем данные + индикатор перезагрузки
-    }
-    
-    return (
-        <div>
-            <h1>{userQuery.data?.name}</h1>
-            <p>{userQuery.data?.email}</p>
-        </div>
-    );
-}
-```
-
-**Возвращаемое значение (ResourceQueryState):**
-
-| Поле               | Тип         | Описание                              |
-|--------------------|-------------|---------------------------------------|
-| `isLoading`        | `boolean`   | Любая загрузка (первая или повторная) |
-| `isInitialLoading` | `boolean`   | Первая загрузка (данных еще нет)      |
-| `isReloading`      | `boolean`   | Перезагрузка (данные уже есть)        |
-| `isDone`           | `boolean`   | Завершен ли запрос                    |
-| `isSuccess`        | `boolean`   | Успешно ли завершен последний запрос  |
-| `isError`          | `boolean`   | Произошла ли ошибка                   |
-| `isLocked`         | `boolean`   | Заблокирован ли ресурс для операцией  |
-| `error`            | `unknown`   | Объект ошибки                         |
-| `data`             | `D["Data"]` | Данные ресурса                        |
-| `args`             | `D["Args"]` | Аргументы последнего запроса          |
-
-**Особенности:**
-- Автоматическая подписка на состояние ресурса
-- Умная инициация: не повторяет запрос для тех же аргументов
-- Поддержка `SKIP` токена для условного пропуска запроса
-- При смене аргументов показывает предыдущие данные во время загрузки новых
-
-### useOperationAgent
-
-Создает агент операции и возвращает кортеж `[trigger, state]`.
-
-```tsx
-import { useOperationAgent } from '@fozy-labs/rx-toolkit';
-import { updateUserOperation } from '../api/updateUserOperation';
-
-function EditUserForm({ user }: { user: User }) {
-    const [updateUser, updateState] = useOperationAgent(updateUserOperation);
-
-    const handleSubmit = async (event: React.FormEvent) => {
-        event.preventDefault();
-        const formData = new FormData(event.target as HTMLFormElement);
-        
-        try {
-            const result = await updateUser({ 
-                id: user.id, 
-                data: Object.fromEntries(formData) 
-            });
-            console.log('Обновлено:', result);
-        } catch (error) {
-            console.error('Ошибка:', error);
-        }
-    };
-
-    return (
-        <form onSubmit={handleSubmit}>
-            <input name="name" defaultValue={user.name} />
-            <input name="email" defaultValue={user.email} />
-            
-            <button type="submit" disabled={updateState.isLoading}>
-                {updateState.isLoading ? 'Сохранение...' : 'Сохранить'}
-            </button>
-            
-            {updateState.isError && (
-                <p className="error">Ошибка: {String(updateState.error)}</p>
-            )}
-        </form>
-    );
-}
-```
-
-**Возвращаемое значение:**
-```typescript
-[
-    trigger: (args: Args) => Promise<Data>,  // Функция запуска операции
-    state: OperationQueryState               // Текущее состояние
-]
-```
-
-**trigger функция:**
-- Возвращает Promise с результатом операции
-- При ошибке Promise реджектится
-- Функция стабильна (не меняется между рендерами)
-
-**state объект:**
-
-| Поле          | Тип         | Описание                  |
-|---------------|-------------|---------------------------|
-| `isInitiated` | `boolean`   | Была ли операция запущена |
-| `isLoading`   | `boolean`   | Выполняется ли операция   |
-| `isDone`      | `boolean`   | Завершена ли операция     |
-| `isSuccess`   | `boolean`   | Успешно ли завершена      |
-| `isError`     | `boolean`   | Произошла ли ошибка       |
-| `error`       | `unknown`   | Объект ошибки             |
-| `data`        | `D["Data"]` | Результат операции        |
-
-### useResourceRef
-
-Возвращает ссылку на элемент кэша ресурса для низкоуровневых операций.
-
-```tsx
-import { useResourceRef, useResourceAgent } from '@fozy-labs/rx-toolkit';
-import { todoResource } from '../api/todoResource';
-
-function TodoItem({ todo }: { todo: Todo }) {
-    const todoQuery = useResourceAgent(todoResource, undefined);
-    const todoRef = useResourceRef(todoResource, undefined);
-    
-    const [pendingTransaction, setPendingTransaction] = useState(null);
-    
-    const handleToggle = () => {
-        // Создаем транзакцию для изменения
-        const transaction = todoRef.patch((draft) => {
-            const item = draft.items.find(i => i.id === todo.id);
-            if (item) item.completed = !item.completed;
-        });
-        
-        if (transaction) {
-            setPendingTransaction(transaction);
-        }
-    };
-    
-    const handleSave = async () => {
-        try {
-            await saveToServer(todo.id, !todo.completed);
-            pendingTransaction?.commit();
-        } catch {
-            pendingTransaction?.abort(); // Откатить изменения
-        }
-        setPendingTransaction(null);
-    };
-    
-    return (
-        <div>
-            <input 
-                type="checkbox" 
-                checked={todo.completed}
-                onChange={handleToggle}
-            />
-            {pendingTransaction && (
-                <>
-                    <button onClick={handleSave}>Сохранить</button>
-                    <button onClick={() => {
-                        pendingTransaction.abort();
-                        setPendingTransaction(null);
-                    }}>
-                        Отмена
-                    </button>
-                </>
-            )}
-        </div>
-    );
-}
-```
-
-**Возвращаемое значение (ResourceRefInstanse):**
-
-| Метод | Описание |
-|-------|----------|
-| `has` | Проверка наличия элемента в кэше |
-| `lock()` | Блокировка ресурса, возвращает `{ unlock }` |
-| `unlockOne()` | Снятие одной блокировки |
-| `patch(fn)` | Создание patch-транзакции |
-| `invalidate()` | Инвалидация кэша |
-| `create(data)` | Создание элемента в кэше |
-
-
----
-
-## Паттерны использования
-
-### Store класс
-
-```tsx
-import { Signal, useSignal } from '@fozy-labs/rx-toolkit';
-
-class CounterStore {
-    count$ = Signal.create(0, 'counter');
-    doubled$ = Signal.compute(() => this.count$() * 2);
-    
-    increment = () => this.count$.set(this.count$() + 1);
-    decrement = () => this.count$.set(this.count$() - 1);
-    reset = () => this.count$.set(0);
-}
-
-// Singleton
-const counterStore = new CounterStore();
-
-function Counter() {
-    const count = useSignal(counterStore.count$);
-    const doubled = useSignal(counterStore.doubled$);
-    
-    return (
-        <div>
-            <p>{count} × 2 = {doubled}</p>
-            <button onClick={counterStore.increment}>+</button>
-            <button onClick={counterStore.decrement}>-</button>
-            <button onClick={counterStore.reset}>Reset</button>
-        </div>
-    );
-}
-```
-
-### Условные запросы
-
-```tsx
-function UserStats({ userId, showStats }) {
-    const statsQuery = useResourceAgent(
-        statsResource,
-        showStats && userId ? { userId } : SKIP
-    );
-    
-    if (!showStats) return null;
-    
-    return <StatsDisplay data={statsQuery.data} />;
-}
-```
-
-### Комбинирование ресурсов
-
-```tsx
-function Dashboard() {
-    const userQuery = useResourceAgent(userResource, { id: currentUserId });
-    const settingsQuery = useResourceAgent(settingsResource, undefined);
-    
-    const isLoading = userQuery.isLoading || settingsQuery.isLoading;
-    const isError = userQuery.isError || settingsQuery.isError;
-    
-    if (isLoading) return <Loader />;
-    if (isError) return <Error />;
-    
-    return (
-        <div>
-            <UserInfo user={userQuery.data} />
-            <Settings settings={settingsQuery.data} />
-        </div>
-    );
-}
-```
+# React интеграция
+
+RxToolkit предоставляет набор React хуков для эффективной интеграции с реактивными системами библиотеки. Все хуки оптимизированы для минимальных ре-рендеров и максимальной производительности.
+
+## Основные хуки
+
+### useSignal
+
+Подписывается на изменения сигнала и возвращает текущее значение.
+
+```tsx
+import { Signal, Computed, useSignal } from '@fozy-labs/rx-toolkit';
+
+const counter$ = Signal.state(0);
+const doubled$ = Signal.compute(() => counter$() * 2);
+
+function Counter() {
+    const count = useSignal(counter$);
+    const doubled = useSignal(doubled$);
+
+    return (
+        <div>
+            <p>Count: {count}</p>
+            <p>Doubled: {doubled}</p>
+            <button onClick={() => counter$.set(counter$.peek() + 1)}>
+                Increment
+            </button>
+        </div>
+    );
+}
+```
+
+**Особенности:**
+- Автоматическая подписка и отписка при размонтировании
+- Не вызывает ре-рендер, если значение не изменилось
+
+---
+
+## RxQuery хуки
+
+### useResourceAgent
+
+Подписывается на состояние ресурса и автоматически инициирует запрос при монтировании или изменении аргументов.
+
+```tsx
+import { useResourceAgent, SKIP } from '@fozy-labs/rx-toolkit';
+import { userResource } from '../api/userResource';
+
+function UserProfile({ userId }: { userId: string | null }) {
+    const userQuery = useResourceAgent(
+        userResource, 
+        userId ? { id: userId } : SKIP
+    );
+
+    if (userQuery.isInitialLoading) {
+        return <div>Загрузка...</div>;
+    }
+    
+    if (userQuery.isError) {
+        return <div>Ошибка: {String(userQuery.error)}</div>;
+    }
+    
+    if (userQuery.isReloading) {
+        // Показываем данные + индикатор перезагрузки
+    }
+    
+    return (
+        <div>
+            <h1>{userQuery.data?.name}</h1>
+            <p>{userQuery.data?.email}</p>
+        </div>
+    );
+}
+```
+
+**Возвращаемое значение (ResourceQueryState):**
+
+| Поле               | Тип         | Описание                              |
+|--------------------|-------------|---------------------------------------|
+| `isLoading`        | `boolean`   | Любая загрузка (первая или повторная) |
+| `isInitialLoading` | `boolean`   | Первая загрузка (данных еще нет)      |
+| `isReloading`      | `boolean`   | Перезагрузка (данные уже есть)        |
+| `isDone`           | `boolean`   | Завершен ли запрос                    |
+| `isSuccess`        | `boolean`   | Успешно ли завершен последний запрос  |
+| `isError`          | `boolean`   | Произошла ли ошибка                   |
+| `isLocked`         | `boolean`   | Заблокирован ли ресурс командой       |
+| `error`            | `unknown`   | Объект ошибки                         |
+| `data`             | `D["Data"]` | Данные ресурса                        |
+| `args`             | `D["Args"]` | Аргументы последнего запроса          |
+
+**Особенности:**
+- Автоматическая подписка на состояние ресурса
+- Умная инициация: не повторяет запрос для тех же аргументов
+- Поддержка `SKIP` токена для условного пропуска запроса
+- При смене аргументов показывает предыдущие данные во время загрузки новых
+
+### useCommandAgent
+
+Создает агент команды и возвращает кортеж `[trigger, state]`.
+
+> **Note:** `useOperationAgent` является deprecated-алиасом для `useCommandAgent` и будет удалён в v0.6.0.
+
+```tsx
+import { useCommandAgent } from '@fozy-labs/rx-toolkit';
+import { updateUserCommand } from '../api/updateUserCommand';
+
+function EditUserForm({ user }: { user: User }) {
+    const [updateUser, updateState] = useCommandAgent(updateUserCommand);
+
+    const handleSubmit = async (event: React.FormEvent) => {
+        event.preventDefault();
+        const formData = new FormData(event.target as HTMLFormElement);
+        
+        try {
+            const result = await updateUser({ 
+                id: user.id, 
+                data: Object.fromEntries(formData) 
+            });
+            console.log('Обновлено:', result);
+        } catch (error) {
+            console.error('Ошибка:', error);
+        }
+    };
+
+    return (
+        <form onSubmit={handleSubmit}>
+            <input name="name" defaultValue={user.name} />
+            <input name="email" defaultValue={user.email} />
+            
+            <button type="submit" disabled={updateState.isLoading}>
+                {updateState.isLoading ? 'Сохранение...' : 'Сохранить'}
+            </button>
+            
+            {updateState.isError && (
+                <p className="error">Ошибка: {String(updateState.error)}</p>
+            )}
+        </form>
+    );
+}
+```
+
+**Возвращаемое значение:**
+```typescript
+[
+    trigger: (args: Args) => Promise<Data>,  // Функция запуска команды
+    state: CommandQueryState                 // Текущее состояние
+]
+```
+
+**trigger функция:**
+- Возвращает Promise с результатом команды
+- При ошибке Promise реджектится
+- Функция стабильна (не меняется между рендерами)
+
+**state объект:**
+
+| Поле          | Тип         | Описание                  |
+|---------------|-------------|---------------------------|
+| `isInitiated` | `boolean`   | Была ли команда запущена  |
+| `isLoading`   | `boolean`   | Выполняется ли команда    |
+| `isDone`      | `boolean`   | Завершена ли команда      |
+| `isSuccess`   | `boolean`   | Успешно ли завершена      |
+| `isError`     | `boolean`   | Произошла ли ошибка       |
+| `error`       | `unknown`   | Объект ошибки             |
+| `data`        | `D["Data"]` | Результат команды         |
+
+### useResourceRef
+
+Возвращает ссылку на элемент кэша ресурса для низкоуровневых операций.
+
+```tsx
+import { useResourceRef, useResourceAgent } from '@fozy-labs/rx-toolkit';
+import { todoResource } from '../api/todoResource';
+
+function TodoItem({ todo }: { todo: Todo }) {
+    const todoQuery = useResourceAgent(todoResource, undefined);
+    const todoRef = useResourceRef(todoResource, undefined);
+    
+    const [pendingTransaction, setPendingTransaction] = useState(null);
+    
+    const handleToggle = () => {
+        // Создаем транзакцию для изменения
+        const transaction = todoRef.patch((draft) => {
+            const item = draft.items.find(i => i.id === todo.id);
+            if (item) item.completed = !item.completed;
+        });
+        
+        if (transaction) {
+            setPendingTransaction(transaction);
+        }
+    };
+    
+    const handleSave = async () => {
+        try {
+            await saveToServer(todo.id, !todo.completed);
+            pendingTransaction?.commit();
+        } catch {
+            pendingTransaction?.abort(); // Откатить изменения
+        }
+        setPendingTransaction(null);
+    };
+    
+    return (
+        <div>
+            <input 
+                type="checkbox" 
+                checked={todo.completed}
+                onChange={handleToggle}
+            />
+            {pendingTransaction && (
+                <>
+                    <button onClick={handleSave}>Сохранить</button>
+                    <button onClick={() => {
+                        pendingTransaction.abort();
+                        setPendingTransaction(null);
+                    }}>
+                        Отмена
+                    </button>
+                </>
+            )}
+        </div>
+    );
+}
+```
+
+**Возвращаемое значение (ResourceRefInstance):**
+
+| Метод | Описание |
+|-------|----------|
+| `has` | Проверка наличия элемента в кэше |
+| `lock()` | Блокировка ресурса, возвращает `{ unlock }` |
+| `unlockOne()` | Снятие одной блокировки |
+| `patch(fn)` | Создание patch-транзакции |
+| `invalidate()` | Инвалидация кэша |
+| `create(data)` | Создание элемента в кэше |
+
+
+---
+
+## Паттерны использования
+
+### Store класс
+
+```tsx
+import { Signal, useSignal } from '@fozy-labs/rx-toolkit';
+
+class CounterStore {
+    count$ = Signal.state(0, 'counter');
+    doubled$ = Signal.compute(() => this.count$() * 2);
+    
+    increment = () => this.count$.set(this.count$() + 1);
+    decrement = () => this.count$.set(this.count$() - 1);
+    reset = () => this.count$.set(0);
+}
+
+// Singleton
+const counterStore = new CounterStore();
+
+function Counter() {
+    const count = useSignal(counterStore.count$);
+    const doubled = useSignal(counterStore.doubled$);
+    
+    return (
+        <div>
+            <p>{count} × 2 = {doubled}</p>
+            <button onClick={counterStore.increment}>+</button>
+            <button onClick={counterStore.decrement}>-</button>
+            <button onClick={counterStore.reset}>Reset</button>
+        </div>
+    );
+}
+```
+
+### Условные запросы
+
+```tsx
+function UserStats({ userId, showStats }) {
+    const statsQuery = useResourceAgent(
+        statsResource,
+        showStats && userId ? { userId } : SKIP
+    );
+    
+    if (!showStats) return null;
+    
+    return <StatsDisplay data={statsQuery.data} />;
+}
+```
+
+### Комбинирование ресурсов
+
+```tsx
+function Dashboard() {
+    const userQuery = useResourceAgent(userResource, { id: currentUserId });
+    const settingsQuery = useResourceAgent(settingsResource, undefined);
+    
+    const isLoading = userQuery.isLoading || settingsQuery.isLoading;
+    const isError = userQuery.isError || settingsQuery.isError;
+    
+    if (isLoading) return <Loader />;
+    if (isError) return <Error />;
+    
+    return (
+        <div>
+            <UserInfo user={userQuery.data} />
+            <Settings settings={settingsQuery.data} />
+        </div>
+    );
+}
+```