@fozy-labs/rx-toolkit 0.5.4 → 0.6.2

package/docs/query/usage/links.md

@@ -0,0 +1,125 @@
+# Связи (Links)
+
+Связь (link) — декларативное соединение между [командой][command] и [ресурсом][resource]. После мутации связь автоматически синхронизирует кэш затронутых ресурсов: инвалидирует, обновляет оптимистично или подставляет данные из ответа сервера.
+
+Связь определяется в колбэке `links` при создании **команды**. Функция `link` принимает конфигурацию с целевым ресурсом и стратегией обновления.
+
+
+## Параметры конфигурации
+
+| Параметр | Тип | Обязательный | Описание |
+|----------|-----|-------------|----------|
+| `resource` | `IResource<TResArgs, TResData>` | да | Целевой [ресурс][resource] |
+| `forwardArgs` | `(commandArgs: TArgs) => TResArgs \| undefined` | да | Маппинг аргументов команды в ключ кэша ресурса. `undefined` — все записи |
+| `invalidate` | `boolean` | нет | Инвалидировать запись после успеха команды |
+| `optimisticUpdate` | `(draft: TResData, commandArgs: TArgs) => void` | нет | Immer-рецепт, применяется немедленно |
+| `update` | `(draft: TResData, commandArgs: TArgs, result: TData) => void` | нет | Immer-рецепт, применяется после успеха |
+
+
+## forwardArgs — адресация записей кэша
+
+`forwardArgs` — единственное обязательное поле. 
+Оно преобразует аргументы команды в ключ кэш-записи ресурса, определяя, **какие именно записи** затронет связь.
+
+Адресация конкретной записи:
+
+```typescript
+link({
+  resource: userResource,
+  forwardArgs: (args) => args.userId,
+  invalidate: true,
+})
+```
+
+> Если `forwardArgs` возвращает аргументы, для которых записи в кэше ещё нет — связь не сработает (нечего обновлять/инвалидировать).
+
+
+## Тайминг выполнения
+
+Стратегии выполняются в разные моменты жизненного цикла команды:
+
+```
+trigger(args)
+  │
+  ├── optimisticUpdate  ← немедленно, до ответа сервера
+  │
+  ├── queryFn(args)     ← сетевой запрос
+  │
+  ├─ OK ─┬── update     ← после успешного ответа (получает result)
+  │      └── invalidate ← после успешного ответа (помечает запись устаревшей)
+  │
+  └─ ERROR ── rollback   ← автоматический откат optimisticUpdate
+```
+
+- **optimisticUpdate** — применяется мгновенно, UI обновляется без ожидания. Использует Immer-патч; при ошибке команды откат происходит автоматически через систему [патчинга][patching].
+- **update** — применяется после успеха, получает `result` из ответа сервера.
+- **invalidate** — помечает запись устаревшей после успеха; ресурс будет перезапрошен при следующем обращении.
+
+
+## Комбинирование стратегий
+
+### В одной связи
+
+`optimisticUpdate` и `invalidate` можно объединить: UI обновляется мгновенно, а после успеха кэш инвалидируется и перезапрашивается с сервера. Это даёт и мгновенный отклик, и гарантию консистентности:
+
+```typescript
+const updateTodoCommand = api.createCommand({
+  queryFn: fetchTodoUpdate,
+  links: (link) => {
+      link({
+          resource: todosResource,
+          forwardArgs: () => undefined,
+          optimisticUpdate: (draft, args) => {
+              const todo = draft.find((t: any) => t.id === args.id);
+              if (todo) todo.done = args.done;
+          },
+          invalidate: true,
+      });
+  },
+});
+```
+
+
+### Несколько связей на одну команду
+
+Команда может затрагивать несколько ресурсов. Каждый ресурс получает собственную связь:
+
+```typescript
+const deleteProjectCommand = api.createCommand({
+  queryFn: fetchProjectDelete,
+  links: (link) => {
+    link({
+      resource: projectResource,
+      forwardArgs: (args) => args.projectId,
+      invalidate: true,
+    });
+    
+    link({
+      resource: projectListResource,
+      forwardArgs: () => undefined,
+      optimisticUpdate: (draft, args) => {
+        const idx = draft.findIndex((p: any) => p.id === args.projectId);
+        if (idx !== -1) draft.splice(idx, 1);
+      },
+      invalidate: true,
+    });
+  },
+});
+```
+
+
+## См. также
+
+- [Команда][command] — создание команд, опции и React-хук `useCommand`
+- [Ресурс][resource] — чтение данных и кэширование
+- [Патчинг][patching] — механизм оптимистичных обновлений и отката
+- [Broadcast][broadcast] — кросс-табовая синхронизация состояния
+- [Потоки данных][dataflows] — общая схема движения данных в Query
+
+
+
+[command]: ./command.md
+[resource]: ./resource.md
+[patching]: ../concepts/patching.md
+[broadcast]: ./broadcast.md
+[dataflows]: ../concepts/dataflows.md

package/docs/query/usage/plugins.md

@@ -0,0 +1,96 @@
+# Плагины
+
+Плагины расширяют возможности API, добавляя методы к [ресурсам][resource] и [командам][command]. Например, встроенный плагин `reactHooksPlugin()` добавляет React-хуки прямо на экземпляры ресурсов.
+
+Плагины передаются при создании API через опцию `plugins`:
+
+```typescript
+import { createApi, reactHooksPlugin } from '@fozy-labs/rx-toolkit';
+
+const api = createApi({
+  plugins: [reactHooksPlugin()],
+});
+```
+
+
+## reactHooksPlugin()
+
+Встроенный плагин для интеграции с React. Добавляет хук `useResource` на каждый ресурс, созданный через API:
+
+```tsx
+const usersResource = api.createResource({
+  queryFn: (args: { page: number }, signal) =>
+    fetch(`/api/users?page=${args.page}`, { signal }).then(r => r.json()),
+});
+
+// Хук доступен благодаря плагину:
+const { data, isLoading } = usersResource.useResource({ page: 1 });
+```
+
+Подробнее о поведении хука — см. раздел «React: useResource» в документации [ресурса][resource].
+
+
+## Написание собственного плагина
+
+Плагин реализует интерфейс `IPlugin`:
+
+```typescript
+interface IPlugin {
+  readonly name: string;
+  install(context: IPluginContext): void;
+  augmentResource?<TArgs, TData>(
+    resource: IResource<TArgs, TData>,
+    options: TResourceOptions<TArgs, TData>,
+  ): Record<string, unknown>;
+  augmentCommand?<TArgs, TData>(
+    command: ICommand<TArgs, TData>,
+    options: TCommandOptions<TArgs, TData>,
+  ): Record<string, unknown>;
+}
+```
+
+- `name` — уникальное строковое имя плагина.
+- `install(context)` — вызывается один раз при `createApi()`. Получает `IPluginContext` с метаинформацией об API.
+- `augmentResource(resource, options)` — вызывается при каждом `createResource()`. Возвращает объект с методами, которые будут добавлены к ресурсу.
+- `augmentCommand(command, options)` — аналогично, вызывается при каждом `createCommand()`. Возвращает объект с методами для команды.
+
+```typescript
+const loggingPlugin: IPlugin = {
+  name: 'LoggingPlugin',
+  install() {},
+  augmentResource(resource) {
+    return {
+      logState(args: unknown) {
+        // Упрощённый пример — getEntry$ принимает аргументы для идентификации кэш-записи
+        console.log(resource.getEntry(args));
+      },
+    };
+  },
+};
+```
+
+
+## Типизация вкладов плагина
+
+Чтобы TypeScript знал о методах, добавленных плагином, используется паттерн условных типов через `PluginResourceContributions`:
+
+```typescript
+type PluginResourceContributions<TPlugin, TArgs, TData> =
+  TPlugin extends { name: 'ReactHooksPlugin' }
+    ? IReactHooksPluginContributions<TArgs, TData>
+    : Record<string, never>;
+```
+
+Тип `PluginAugmentations` объединяет вклады всех плагинов в массиве и добавляет их к возвращаемому типу `createResource()`. Благодаря этому `usersResource.useResource(...)` корректно типизирован, когда в `plugins` передан `reactHooksPlugin()`.
+
+Для собственного плагина добавьте новую ветку в `PluginResourceContributions`, аналогичную ветке `ReactHooksPlugin`.
+
+
+## См. также
+
+- [Ресурс][resource] — основной примитив запросов, который расширяется плагинами.
+- [Команда][command] — примитив мутаций, также расширяемый через плагины.
+
+
+[resource]: ./resource.md
+[command]: ./command.md

package/docs/query/usage/resource.md

@@ -0,0 +1,206 @@
+# Ресурс (Resource)
+
+Ресурс — абстракция для **чтения данных** с автоматическим кэшированием и stale-while-revalidate (SWR). Для операций записи используйте [команду][command].
+
+Аналог: `useQuery` в TanStack Query, `query endpoint` в RTK Query.
+
+
+## Создание ресурса
+
+```typescript
+const usersResource = api.createResource({
+  queryFn: async (args: { page: number }, abortSignal) => {
+    const res = await fetch(`/api/users?page=${args.page}`, { signal: abortSignal });
+    return res.json();
+  },
+});
+```
+
+`queryFn` — единственная обязательная опция. Принимает аргументы запроса и `AbortSignal`, возвращает промис с данными. При отмене запроса (смена аргументов, размонтирование) сигнал срабатывает автоматически.
+
+
+## Опции
+
+Полный список опций — см. [API-справочник ресурса][api-resource].
+
+
+## API ресурса
+
+Полный список методов — см. [API-справочник ресурса][api-resource].
+
+
+## React: useResource
+
+Для работы в React подключите `reactHooksPlugin()` при создании API:
+
+```typescript
+import { createApi, reactHooksPlugin } from '@fozy-labs/rx-toolkit';
+
+const api = createApi({
+  plugins: [reactHooksPlugin()],
+});
+```
+
+`useResource` — метод на экземпляре ресурса, доступный после подключения плагина:
+
+```tsx
+function UsersList({ page }: { page: number }) {
+  const { data, error, isLoading } = usersResource.useResource({ page });
+
+  if (isLoading) return <Spinner />;
+  if (error) return <ErrorMessage error={error} />;
+
+  return (
+    <ul>
+      {data.map(user => <li key={user.id}>{user.name}</li>)}
+    </ul>
+  );
+}
+```
+
+Поведение хука:
+
+1. При монтировании — запускает запрос с переданными аргументами.
+2. При изменении аргументов — автоматически перезапрашивает данные.
+3. При размонтировании — отписывается. Кэш-запись сохраняется в течение `retentionTime`.
+4. При повторном монтировании с теми же аргументами — данные берутся из кэша мгновенно.
+
+
+## Условные запросы
+
+Передайте `SKIP` вместо аргументов, чтобы отложить запрос:
+
+```tsx
+import { SKIP } from '@fozy-labs/rx-toolkit';
+
+function UserProfile({ userId }: { userId: string | null }) {
+  const { data, isLoading } = userResource.useResource(
+    userId ? { id: userId } : SKIP,
+  );
+
+  if (!userId) return <p>Выберите пользователя</p>;
+  if (isLoading) return <Spinner />;
+  return <h1>{data.name}</h1>;
+}
+```
+
+`SKIP` полностью останавливает наблюдение — запрос не выполняется, состояние сбрасывается в `idle`.
+
+
+## Состояния ресурса
+
+`useResource` возвращает объект с полями `status`, `data`, `error` и булевыми флагами:
+
+| Поле | Тип | Описание |
+|---|---|---|
+| `status` | `string` | `'idle'` · `'pending'` · `'success'` · `'error'` · `'refreshing'` · `'refresh-error'` |
+| `data` | `TData \| null` | Данные последнего успешного ответа. Сохраняются при `refreshing`. |
+| `error` | `unknown` | Ошибка последнего запроса. |
+| `isLoading` | `boolean` | `true` при любом незавершённом запросе. |
+| `isInitialLoading` | `boolean` | `true` только при первой загрузке (данных ещё нет). |
+| `isSuccess` | `boolean` | `true` когда данные получены. |
+| `isError` | `boolean` | `true` при ошибке. |
+| `isRefreshing` | `boolean` | `true` при фоновом обновлении (SWR). |
+| `isRefreshError` | `boolean` | `true` при ошибке фонового обновления. |
+
+### Фоновое обновление (refresh)
+
+Вызов `refresh(args)` или `trigger(args, true)` обновляет данные **без потери текущего отображения**. Пользователь продолжает видеть прежние данные, пока в фоне выполняется новый запрос. Когда ответ приходит — данные обновляются на месте; если запрос падает с ошибкой, прежние данные сохраняются, а статус переходит в `refresh-error`.
+
+### Плавная смена аргументов (SWR)
+
+Когда аргументы `useResource` меняются (например, пользователь переключает страницу), компонент **не сбрасывается в пустое состояние**. Вместо этого на экране остаются данные предыдущего запроса, пока загружаются новые. Как только новые данные готовы, они автоматически заменяют старые.
+
+
+## Императивный API
+
+### trigger
+
+```typescript
+const data = await usersResource.trigger({ page: 1 });
+```
+
+Запускает `queryFn` и возвращает промис с результатом. Параллельные вызовы с одинаковыми аргументами дедуплицируются — возвращается один и тот же промис.
+
+### refresh
+
+```typescript
+usersResource.refresh({ page: 1 });
+```
+
+Запускает повторный запрос для кэш-записи. Если у записи есть активные подписчики — запрос выполняется немедленно. Без подписчиков — данные будут перезапрошены при следующем обращении.
+
+
+### getEntry
+
+Синхронно возвращает кэш-запись для указанных аргументов, или `null` если данные ещё не запрашивались. С флагом `doInitiate = true` — создаёт запись и запускает загрузку, если её ещё нет.
+
+```ts
+// Проверить, есть ли данные в кэше
+const entry = usersResource.getEntry({ page: 1 });
+if (entry) {
+  console.log(entry.machine$().data);
+}
+```
+
+
+### getEntry$
+
+Реактивный аналог `getEntry`. Вызывает сигнал внутри, поэтому должен использоваться в реактивном контексте (`Signal.compute`, `Signal.effect` и т. д.). Возвращает кэш-запись или `null`.
+
+```ts
+const entry$ = Signal.compute(() => usersResource.getEntry$({ page: page$() }));
+```
+
+### createAgent
+
+Агент — реактивный наблюдатель ресурса.
+Он отслеживает текущую и при необходимости предыдущую запись кэша,
+объединяя их в плоский вычисляемый сигнал.
+Агент является строительным блоком для React-хука `useResource` и не требует явного уничтожения — внутренние сигналы деактивируются при потере подписчиков.
+Полная таблица методов и статусов — в [API агента ресурса][api-res-agent].
+
+```ts
+const agent = usersResource.createAgent();
+agent.start({ page: 1 });
+// agent.state$() → { status: "pending", data: null, isInitialLoading: true, ... }
+```
+
+При смене аргументов через `start(newArgs)` агент реализует SWR-поведение:
+    если предыдущий запрос содержит данные (статус `success` или `refreshing`),
+    они сохраняются в `data`, а `status` переключается на `"refreshing"` до получения нового ответа.
+Это позволяет показывать устаревшие данные вместо пустого состояния.
+
+```ts
+agent.start({ page: 2 }); // SWR: data от page:1, status: "refreshing"
+agent.start(SKIP);        // idle: data: null, status: "idle"
+```
+
+
+## Связи (Links)
+
+Связи позволяют декларативно связать команду с ресурсами — подробнее в [руководстве по связям][links].
+
+
+## Хуки жизненного цикла
+
+Хуки позволяют реагировать на события кэша — подробнее в [руководстве по жизненному циклу][lifecycle].
+
+
+## См. также
+
+- [Команда][command] — мутации (создание, обновление, удаление)
+- [Машина состояний запроса][machine] — детали переходов между статусами
+- [Кэш][cache] — система кэширования записей
+- [Агент][agent] — SWR-наблюдатель, связывающий UI с записью кэша
+- [Кросс-табовая синхронизация][broadcast] — синхронизация кэша между вкладками
+
+[command]: ./command.md
+[machine]: ../concepts/machine.md
+[api-resource]: ../api/resource.md
+[lifecycle]: ./lifecycle.md
+[links]: ./links.md
+[cache]: ../concepts/cache.md
+[agent]: ../concepts/agent.md
+[api-res-agent]: ../api/resource-agent.md
+[broadcast]: ./broadcast.md

package/docs/query/usage/snapshot.md

@@ -0,0 +1,80 @@
+# SSR и гидрация (Snapshot)
+
+Снимок (snapshot) позволяет сериализовать состояние кэша на сервере и передать его клиенту, чтобы избежать повторных запросов при гидрации. Механизм работает как для [ресурсов][resource], так и для [команд][command].
+
+
+## getSnapshot()
+
+Метод `api.getSnapshot()` собирает **только успешные** записи всех зарегистрированных ресурсов и возвращает объект `TApiSnapshot`:
+
+```typescript
+const snapshot = api.getSnapshot();
+// → { version, keyPrefix, timestamp, resources: { ... } }
+```
+
+Каждая запись содержит `args`, `data` и `updatedAt`. Записи в состояниях pending, error и refreshing — пропускаются.
+
+
+## initialSnapshot
+
+На клиенте снимок передаётся в `createApi`:
+
+```typescript
+const api = createApi({
+  initialSnapshot: snapshot,
+});
+```
+
+Гидрация происходит **лениво**: при вызове `createResource()` библиотека ищет соответствующий slice в снимке и восстанавливает кэш-записи. После гидрации slice удаляется из внутреннего хранилища (consume-паттерн). Вызов `resetAll()` обнуляет сохранённый снимок целиком.
+
+При загрузке проверяется `version` и `keyPrefix` — при несовпадении выбрасывается ошибка.
+
+
+## snapshotValidTime
+
+Опция `snapshotValidTime` определяет, сколько миллисекунд данные из снимка считаются актуальными. Доступна на уровне [API][api-readme] и на уровне отдельного ресурса (ресурс-уровень приоритетнее).
+
+| Значение | Поведение |
+|---|---|
+| `false` (по умолчанию) | Данные из снимка считаются всегда валидными. |
+| `number` (мс) | Если `Date.now() - updatedAt > snapshotValidTime`, запись автоматически инвалидируется после гидрации. |
+
+Инвалидация запускает перезапрос — компонент получит свежие данные без дополнительного кода.
+
+
+## Жизненный цикл
+
+1. **Сервер** — `api.getSnapshot()` сериализует успешные записи кэша в `TApiSnapshot`.
+2. **Передача** — снимок передаётся клиенту как JSON (через `<script>`, props, cookie и т.д.).
+3. **Создание API** — `createApi({ initialSnapshot })` валидирует версию и keyPrefix, сохраняет deep-клон.
+4. **Гидрация ресурсов** — каждый `createResource()` достаёт свой slice и восстанавливает записи в [кэш][cache].
+5. **Авто-инвалидация** — если задан `snapshotValidTime` и запись устарела, она инвалидируется с перезапросом.
+6. **Consume** — использованный slice удаляется; `resetAll()` обнуляет снимок целиком.
+
+
+## Что сериализуется
+
+Каждая [успешная запись][cache] содержит три поля:
+
+| Поле | Описание |
+|---|---|
+| `args` | Аргументы запроса |
+| `data` | Данные ответа |
+| `updatedAt` | Время последнего успешного ответа |
+
+Версия снимка (`version`) проверяется при загрузке — при несовпадении гидрация невозможна.
+
+
+## См. также
+
+- [Кэш][cache] — управление кэш-записями и жизненный цикл GC
+- [Машина состояний][machine] — восстановление из снимка через `Machine.fromSnapshot()`
+- [API-справочник][api-readme] — таблица опций `initialSnapshot`, `snapshotValidTime`, `getSnapshot()`
+
+---
+
+[resource]: ./resource.md
+[command]: ./command.md
+[cache]: ../concepts/cache.md
+[machine]: ../concepts/machine.md
+[api-readme]: ../api/README.md