@fozy-labs/rx-toolkit 0.5.3 → 0.6.0

package/docs/query/concepts/patching.md

@@ -0,0 +1,85 @@
+# Оптимистичные обновления (Patching)
+
+Патч мгновенно применяет изменения к данным в [кэше][cache], не дожидаясь ответа сервера.
+Пользователь видит результат сразу; при ошибке — данные откатываются.
+Механизм основан на Immer.
+
+
+## Жизненный цикл патча
+
+```mermaid
+stateDiagram-v2
+    [*] --> pending : queryCacheEntry.createPatch(patchFn)
+    pending --> committed : handle.commit()
+    pending --> aborted : handle.abort()
+```
+
+- **pending** — патч создан, изменения отражены в `data`, но сервер ещё не подтвердил операцию.
+- **committed** — сервер подтвердил; патч вливается в базовые данные при следующем ребейсе.
+- **aborted** — операция отменена; `inversePatches` откатывают изменения.
+
+
+## patchState
+
+Когда хотя бы один патч активен, в состоянии [машины][machine] появляется поле `patchState`:
+
+| Поле | Описание                                                        |
+|------|-----------------------------------------------------------------|
+| `originalData` | Данные до применения первого патча                              |
+| `patches[]` | Стек патчей |
+| `isConsistencyViolation` | Флаг нарушения консистентности (см. ниже)                       |
+
+Пока `patchState` присутствует: `data` = результат применения всех патчей, `originalData` = нетронутые серверные данные. Когда все патчи завершены — `patchState` сбрасывается в `null`.
+
+
+## Стек патчей
+
+Каждый вызов `createPatch` добавляет новый патч в стек. `originalData` фиксируется при создании первого патча, но может изменяться, см "Поведение при аборте".
+Immer-рецепты накладываются поверх текущего `data` (уже содержащего предыдущие патчи), а не поверх `originalData`.
+
+
+## Ребейс при обновлении
+
+Когда сервер возвращает свежие данные (переход `refreshing → success`), патчи переигрываются на новой базе.
+Если после ребейса pending-патчей не осталось — `patchState` очищается.
+
+
+## Поведение при аборте
+
+Аборт требует применения обратного immer-патча к `originalData`.
+Но при наличии множественных патчей, происходит переигрывание всех патчей поверх `originalData`.
+
+**Для упрощения расчетов (при переигрывании)**:
+- все независимые завершенные патчи (те все `committed` и `aborted`, которые были созданы до первого `pending`) - вливаются в `originalData` и удаляются из стека;
+- все `pending` патчи и зависимые от них `committed` и `aborted` - переигрываются поверх обновленного `originalData`, результат сохраняется в `data`, эти патчи остаются в стеке;
+- если не было `pending` патчей, то `patchState` очищается.
+
+В результате переигрывания, может возникнуть нарушение консистентности (см. ниже).
+
+## Нарушение консистентности
+
+Если при ребейсе или аборте нарушится порядок зависимых патчей (immer не может разрешить изменения) — выставляется `isConsistencyViolation = true`.
+В этом случае стек патчей очищается (`data` остается пропатченой) и запускается автоматическая инвалидация.
+
+
+## Декларативный API
+
+С типичным сценарием «мутация + оптимистичное обновление» описано в руководстве по [связям][links].
+
+
+## См. также
+
+- [Машина состояний][machine] — патчи применяются к состояниям `success`, `refreshing`, `refresh-error`.
+- [Кэш][cache] — запись кэша хранит `patchState` и предоставляет `createPatch`.
+- [Broadcast][broadcast] — кросс-табовая синхронизация, включая передачу патчей.
+- [Использование ресурсов][usage-res] — оптимистичные обновления в контексте ресурса.
+- [Использование команд][usage-cmd] — оптимистичные обновления в контексте команды.
+- [Связи (links)][links] — декларативный `optimisticUpdate` через `link()`.
+
+
+[machine]: machine.md
+[cache]: cache.md
+[broadcast]: ../usage/broadcast.md
+[usage-res]: ../usage/resource.md
+[usage-cmd]: ../usage/command.md
+[links]: ../usage/links.md

package/docs/query/usage/broadcast.md

@@ -0,0 +1,188 @@
+# Кросс-табовая синхронизация (Broadcast)
+
+Кросс-табовая синхронизация позволяет нескольким вкладкам браузера разделять состояние кэша.
+Когда вкладке нужны данные, она перед выполнением `queryFn` отправляет запрос (REQ) через `syncDriver`;
+    если другая вкладка уже располагает данными, она отвечает (RES) — и сетевой запрос не выполняется.
+Внутри это реализовано через хук `beforeQuery`, который `createApi` автоматически внедряет в каждый ресурс с включённой синхронизацией:
+    непосредственно перед вызовом `queryFn` хук отправляет REQ через `syncDriver` и, получив RES, возвращает данные из другой вкладки, минуя сеть.
+Синхронизация управляется через `syncDriver` — опцию `createApi`,
+    принимающую реализацию интерфейса `ISyncDriver`.
+
+
+## Подключение syncDriver
+
+Опция `syncDriver` задаётся при вызове `createApi`:
+
+```typescript
+import { createApi, broadcastSyncDriver } from '@fozy-labs/rx-toolkit';
+
+const api = createApi({
+  keyPrefix: 'my-api',
+  defaultSync: 'resources',
+  syncDriver: broadcastSyncDriver(),
+});
+```
+
+
+## broadcastSyncDriver
+
+Встроенная реализация `ISyncDriver` на базе [BroadcastChannel API][broadcast-channel].
+
+| Параметр  | Тип      | По умолчанию                | Описание                                                                       |
+|-----------|----------|-----------------------------|--------------------------------------------------------------------|
+| `channel` | `string` | `"rx-toolkit:{keyPrefix}"` | Имя `BroadcastChannel`. Если не указано, генерируется из `keyPrefix` API. |
+
+```typescript
+// Канал по умолчанию — "rx-toolkit:my-api"
+const api = createApi({
+  keyPrefix: 'my-api',
+  syncDriver: broadcastSyncDriver(),
+});
+
+// Явное имя канала
+const api = createApi({
+  keyPrefix: 'my-api',
+  syncDriver: broadcastSyncDriver({ channel: 'shared-state' }),
+});
+```
+
+
+## Управление синхронизацией
+
+Опции определяющие, участвует ли ресурс или команда в синхронизации.
+
+| Сущность    | Опция         | Принимаемое значение           | По умолчанию        |
+|-------------|---------------|--------------------------------|---------------------|
+| **api**     | `defaultSync` | `resources` \| `all` \| `none` | `none`              |
+| **Ресурс**  | `sync`        | `boolean`                      | **api defaultSync** |
+| **Команда** | `sync`        | `boolean`                      | **api defaultSync** |
+
+> Если `syncDriver` не задан в `createApi`, то синхронизация работать не будет.
+
+```typescript
+const getCatalog = api.createResource({
+  key: 'catalog',
+  queryFn: fetchCatalog,
+  sync: true,
+});
+
+// Приватные данные пользователя — отключаем sync
+const getProfile = api.createResource({
+  key: 'profile',
+  queryFn: fetchProfile,
+  sync: false,
+});
+
+// Мутация, результат которой нужен всем вкладкам
+const markRead = api.createCommand({
+  key: 'markRead',
+  queryFn: markNotificationRead,
+  sync: true,
+});
+```
+
+
+## Что синхронизируется
+
+Когда вкладка получает REQ и запись находится в одном из состояний ниже,
+она отвечает RES с соответствующими данными:
+
+| Состояние [машины][machine] | Данные в RES   |
+|-----------------------------|----------------|
+| `pending`                   | —              |
+| `success`                   | `data`         |
+| `success` (с патчами)       | `originalData` |
+| `error`                     | —              |
+| `refreshing`                | —              |
+| `refresh-error`             | —              |
+
+
+## Кастомный syncDriver
+
+`ISyncDriver` — транспортно-агностичный контракт. 
+Встроенная реализация — `broadcastSyncDriver`, но можно создать свою (WebSocket, SharedWorker и т. д.).
+
+
+### ISyncDriver
+
+| Метод        | Сигнатура                                       | Описание                                                                |
+|--------------|--------------------------------------------------|-------------------------------------------------------------------------|
+| `connect`    | `(onMessage: (msg: ISyncMessage) => void) => void` | Подключиться к каналу. `onMessage` вызывается при получении внешних сообщений |
+| `disconnect` | `() => void`                                     | Отключиться от канала и освободить ресурсы                              |
+| `send`       | `(message: ISyncMessage) => void`                | Отправить сообщение                |
+
+
+### ISyncMessage
+
+| Поле        | Тип                              | Описание                                  |
+|-------------|----------------------------------|-------------------------------------------|
+| `type`      | `REQ` \| `RES`                   | Тип сообщения: запрос, ответ или ошибка   |
+| `reqId`     | `string`                         | Идентификатор запроса (для связи REQ-RES) |
+| `keys`      | `[<prefix>, <key>, <entry_key>]` | Ключи                                     |
+| `data`      | `any`                            | Данные (для RES)                          |
+
+
+## Полный пример
+
+Пример демонстрирует `createApi` с `broadcastSyncDriver`,
+    ресурс и команду со связями — и поведение на двух вкладках.
+
+```typescript
+import { createApi, broadcastSyncDriver, reactHooksPlugin } from '@fozy-labs/rx-toolkit';
+
+const api = createApi({
+  keyPrefix: 'main-api',
+  syncDriver: broadcastSyncDriver(),
+  plugins: [reactHooksPlugin()],
+  defaultSync: 'resources', // по умолчанию синхронизировать только ресурсы
+});
+
+// Ресурс — sync: true (наследуется от defaultSync: 'resources')
+const todosResource = api.createResource({
+  key: 'todos',
+  queryFn: async () => {
+    const res = await fetch('/api/todos');
+    return res.json();
+  },
+});
+```
+
+```tsx
+function TodoApp() {
+  const { data: todos, isLoading } = todosResource.useResource();
+
+  if (isLoading) return <p>Загрузка...</p>;
+
+  return (
+    <div>
+      <ul>
+        {todos.map((t: any) => <li key={t.id}>{t.text}</li>)}
+      </ul>
+      <button disabled={isSaving} onClick={() => trigger({ text: 'Новая задача' })}>
+        Добавить
+      </button>
+    </div>
+  );
+}
+```
+
+
+## См. также
+
+- [API-справочник][api-readme] — полная таблица опций `createApi`
+- [Связи (Links)][links] — декларативное соединение команд и ресурсов
+- [Патчинг][patching] — механизм оптимистичных обновлений и отката
+- [Ресурс (API)][api-resource] — опции ресурса, включая `sync`
+- [Кэш][cache] — управление кэш-записями и их жизненным циклом
+- [Потоки данных][dataflows] — диаграммы кросс-табовой синхронизации
+
+
+
+[links]: ./links.md
+[api-readme]: ../api/README.md
+[api-resource]: ../api/resource.md
+[cache]: ../concepts/cache.md
+[dataflows]: ../concepts/dataflows.md
+[machine]: ../concepts/machine.md
+[patching]: ../concepts/patching.md
+[broadcast-channel]: https://developer.mozilla.org/en-US/docs/Web/API/BroadcastChannel

package/docs/query/usage/command.md

@@ -0,0 +1,203 @@
+# Команда (Command)
+
+Команда — абстракция для **операций записи** (мутаций): создание, обновление, удаление данных. Для чтения данных используйте [ресурс][resource].
+
+Аналог: `useMutation` в TanStack Query, `mutation endpoint` в RTK Query.
+
+
+## Создание команды
+
+```typescript
+const addTodoCommand = api.createCommand({
+  queryFn: async (args: { text: string }) => {
+    const res = await fetch('/api/todos', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(args),
+    });
+    return res.json();
+  },
+  links: (link) => link({
+    resource: todosResource,
+    forwardArgs: () => undefined,
+    invalidate: true,
+  }),
+});
+```
+
+`queryFn` — единственная обязательная опция. Принимает аргументы мутации, возвращает промис с данными. 
+`links` — колбэк, описывающий связи с ресурсами, которые нужно обновить после выполнения команды.
+
+
+## Опции
+
+Полный список опций — см. [API-справочник команды][api-command].
+
+
+## API команды
+
+Полный список методов — см. [API-справочник команды][api-command].
+
+
+## React: useCommand
+
+Для работы в React подключите `reactHooksPlugin()` при создании API:
+
+```typescript
+import { createApi, reactHooksPlugin } from '@fozy-labs/rx-toolkit';
+
+const api = createApi({
+  plugins: [reactHooksPlugin()],
+});
+```
+
+`useCommand` — метод на экземпляре команды, доступный после подключения плагина:
+
+```tsx
+function AddTodoForm() {
+  const [trigger, { data, error, isLoading }] = addTodoCommand.useCommand();
+  const [text, setText] = React.useState('');
+
+  const handleSubmit = async (e: React.FormEvent) => {
+    e.preventDefault();
+    if (!text.trim()) return;
+    await trigger({ text });
+    setText('');
+  };
+
+  return (
+    <form onSubmit={handleSubmit}>
+      <input value={text} onChange={e => setText(e.target.value)} disabled={isLoading} />
+      <button disabled={isLoading}>Добавить</button>
+      {error && <p>Ошибка: {String(error)}</p>}
+    </form>
+  );
+}
+```
+
+Поведение хука:
+
+1. Хук не запускает запрос при монтировании — мутация выполняется только при вызове `trigger`.
+2. `trigger(args)` запускает `queryFn` и возвращает `Promise<TData>`.
+3. Состояние (`isLoading`, `isSuccess`, `isError`) обновляется реактивно.
+
+## Состояния команды
+
+`useCommand` возвращает `[trigger, state]`, где `state` содержит:
+
+| Поле | Тип | Описание |
+|---|---|---|
+| `status` | `string` | `'idle'` · `'pending'` · `'success'` · `'error'` |
+| `data` | `TData \| null` | Данные последнего успешного ответа. |
+| `error` | `unknown` | Ошибка последнего запроса. |
+| `isLoading` | `boolean` | `true` при выполнении мутации. |
+| `isSuccess` | `boolean` | `true` когда мутация завершилась успешно. |
+| `isError` | `boolean` | `true` при ошибке мутации. |
+
+
+## Императивный API
+
+### trigger
+
+```typescript
+// Без ключа — создаётся автоматическая кэш-запись
+const data = await addTodoCommand.trigger({ text: 'Новая задача' });
+
+// С явным ключом — привязывает результат к кэш-записи 'my-mutation-1'
+const data = await addTodoCommand.trigger({ text: 'Новая задача' }, 'my-mutation-1');
+```
+
+Запускает `queryFn` и возвращает промис с результатом. Необязательный второй аргумент `key` идентифицирует кэш-запись.
+
+### getEntry
+
+Синхронно возвращает кэш-запись для указанного ключа, или `null` если записи нет.
+
+```typescript
+const entry = addTodoCommand.getEntry('my-mutation-1');
+if (entry) {
+  console.log(entry.machine$().data);
+}
+```
+
+### getEntry$
+
+Реактивный аналог `getEntry`. Вызывает сигнал внутри, поэтому должен использоваться в реактивном контексте (`Signal.compute`, `Signal.effect` и т. д.). Возвращает кэш-запись или `null`.
+
+```ts
+const entry$ = Signal.compute(() => addTodoCommand.getEntry$('my-mutation-1'));
+```
+
+### createAgent
+
+Создаёт агент — реактивный наблюдатель за командой. Принимает опциональный `key` для привязки к конкретной кэш-записи.
+Полная таблица методов и статусов — в [API агента команды][api-cmd-agent].
+
+```typescript
+const agent = addTodoCommand.createAgent('my-mutation-1');
+
+// trigger через агент
+agent.trigger({ text: 'New todo' });
+// agent.state$() → { status: "pending", data: null, isLoading: true, ... }
+```
+
+
+## Кэш-ключ команды
+
+Кэш-ключ команды — это строка.
+По умолчанию ключ генерируется автоматически (таймстамп + индекс при нескольких вызовах в одном таймстампе),
+поэтому каждый вызов создаёт отдельную кэш-запись.
+
+Способ указания ключа зависит от API:
+
+- **Императивно** — ключ передаётся вторым аргументом в метод `trigger`:
+
+```typescript
+const data = await addTodoCommand.trigger({ text: 'Задача' }, 'my-mutation-1');
+```
+
+- **React-хук** — ключ задаётся на уровне `useCommand`, а функция `trigger` вызывается только с `args`:
+
+```tsx
+const [trigger, state] = addTodoCommand.useCommand('my-mutation-1');
+await trigger({ text: 'Задача' });
+```
+
+- **Агент** — ключ передаётся в `createAgent` и может меняться с помощью методов `trigger` или `setKey`:
+
+```typescript
+const agent = addTodoCommand.createAgent('my-mutation-1');
+agent.trigger({ text: 'Задача' }, 'my-mutation-2');
+agent.setKey('my-mutation-3');
+```
+
+Разные потребители могут синхронизировать состояние, используя один и тот же ключ.
+
+
+## Связи (Links)
+
+Связи позволяют декларативно связать команду с ресурсами — подробнее в [руководстве по связям][links].
+
+
+## Хуки жизненного цикла
+
+Хуки позволяют реагировать на события кэша — подробнее в [руководстве по жизненному циклу][lifecycle].
+
+
+## См. также
+
+- [Ресурс][resource] — чтение данных с кэшированием и SWR
+- [Машина состояний][machine] — детали переходов между статусами
+- [Система кэширования][cache] — жизненный цикл записей кэша
+- [Агент][agent] — реактивный наблюдатель, транслирующий состояние в UI
+- [Broadcast][broadcast] — синхронизация между вкладками; команды поддерживают опцию `sync: true`
+
+[resource]: ./resource.md
+[machine]: ../concepts/machine.md
+[cache]: ../concepts/cache.md
+[agent]: ../concepts/agent.md
+[broadcast]: ./broadcast.md
+[api-command]: ../api/command.md
+[api-cmd-agent]: ../api/command-agent.md
+[lifecycle]: ./lifecycle.md
+[links]: ./links.md

package/docs/query/usage/lifecycle.md

@@ -0,0 +1,114 @@
+# Хуки жизненного цикла (Lifecycle Hooks)
+
+Хуки жизненного цикла позволяют реагировать на события кэш-записей.
+Доступны как для [ресурсов][resource], так и для [команд][command].
+Полный список параметров — в API-справочнике ([ресурс][api-resource],
+    [команда][api-command]).
+
+
+## onCacheEntryAdded
+
+Вызывается **один раз** при создании кэш-записи для конкретных аргументов. 
+Колбэк получает `args` и объект контекста `ctx`:
+
+| Свойство ctx | Тип                                 | Описание                                                                                                |
+|---|-------------------------------------|---------------------------------------------------------------------------------------------------------|
+| `entry` | `CacheEntry` (ресурса или команды) | Текущая кэш-запись.                                                                                     |
+| `$cacheDataLoaded` | `Promise<TData>`                    | Разрешается при первом успешном ответе. Отклоняется, если запись удалена до успешного получения данных. |
+| `$cacheEntryRemoved` | `Promise<void>`                     | Разрешается при удалении записи из кэша.                                                                |
+
+
+```typescript
+const messagesResource = api.createResource({
+    queryFn: (chatId: string) => fetch(`/api/chats/${chatId}/messages`).then(r => r.json()),
+    onCacheEntryAdded: async (chatId, { $cacheDataLoaded, $cacheEntryRemoved }) => {
+        console.log('Cache entry added for chatId:', chatId);
+
+        await $cacheDataLoaded;
+        
+        console.log('Initial data loaded for chatId:', chatId);
+        
+        await $cacheEntryRemoved;
+        
+        console.log('Cache entry removed for chatId:', chatId);
+    }
+});
+```
+
+Хук работает аналогично и для [команд][command].
+
+
+## onQueryStarted
+
+Функция, которая вызывается при запуске каждого отдельного запроса. 
+Позволяет выполнять код на протяжении всего жизненного цикла отдельного запроса.
+
+Колбэк получает `args` и объект контекста `ctx`:
+
+| Свойство ctx | Тип                                 | Описание                                                             |
+|---|-------------------------------------|----------------------------------------------------------------------|
+| `entry` | `CacheEntry` (ресурса или команды) | Текущая кэш-запись.                                                  |
+| `$queryFulfilled` | `Promise<{ data: TData }>`          | Разрешается с данными при успехе. Отклоняется при ошибке или аборте. |
+
+```typescript
+const userResource = api.createResource({
+  queryFn: (id: number) => fetch(`/api/users/${id}`).then(r => r.json()), 
+  onQueryStarted: async (args, { $queryFulfilled }) => {
+      console.log('Query started with args:', args);
+      
+      const { data } = await $queryFulfilled;
+      
+      console.log('Query succeeded with data:', data);
+    },
+});
+```
+
+Хук работает аналогично и для [команд][command].
+
+
+## Обработка ошибок
+
+Ошибки внутри колбэков **подавляются автоматически** — не выбрасываются наружу и не влияют на основной поток запроса. 
+При необходимости (например, для предотвращения утечек памяти) оборачивайте `$queryFulfilled` и  `$cacheDataLoaded` в `try/catch`:
+
+```typescript
+onCacheEntryAdded: async (id, { $cacheDataLoaded, entry }) => {
+    try {
+        const connection = createUserConnection(id);
+        const { data } = await $cacheDataLoaded;
+    } catch {
+        connection.close('unused');
+        return;
+    }
+
+    connection.onUserUpdated((partialUser) => {
+        const patch = entry.patch((draft) => {
+            Object.assign(draft, partialUser);
+        });
+
+        path.commit();
+    });
+
+    await $cacheEntryRemoved;
+
+    connection.close('disposed');
+},
+```
+
+
+## См. также
+
+- [Кэш][cache] — управление кэш-записями и их жизненным циклом
+- [Ресурс][resource] — чтение данных и кэширование
+- [Команда][command] — мутации и побочные эффекты
+- [Потоки данных][dataflows] — диаграммы жизненного цикла запросов
+- [API: ресурс][api-resource] — полная таблица параметров ресурса
+- [API: команда][api-command] — полная таблица параметров команды
+
+
+[cache]: ../concepts/cache.md
+[resource]: ./resource.md
+[command]: ./command.md
+[dataflows]: ../concepts/dataflows.md
+[api-resource]: ../api/resource.md
+[api-command]: ../api/command.md