@fozy-labs/rx-toolkit 0.5.4 → 0.6.0

package/docs/query/api/_CacheEntry.md

@@ -0,0 +1,39 @@
+# Запись кэша (CacheEntry) — API
+
+Базовый реактивный контейнер, хранящий произвольное состояние `TState` с автоматической сборкой мусора (GC).
+
+
+## Опции
+
+| Опция                | Тип                         | По умолчанию        | Описание                                                                                                |
+|----------------------|-----------------------------|---------------------|---------------------------------------------------------------------------------------------------------|
+| `initialState`       | `TState`                    | (Обязательное поле) | Начальное состояние. Устанавливается при создании записи.                                               |
+| `retentionTime`      | `number \| false`           | (Обязательное поле) | Время (мс) удержания записи после отписки последнего подписчика. `false` — не удалять.                  |
+| `devtoolsKey`        | `string`                    | (Обязательное поле) | Ключ для отображения в DevTools.                                                                        |
+| `beforeDevtoolsPush` | `(state: TState) => TState` | —                   | Функция для изменения состояния перед отправкой в DevTools. Полезно для удаления чувствительных данных. |
+
+
+## Свойства
+
+| Свойство     | Тип                    | Описание                                                                     |
+|--------------|------------------------|------------------------------------------------------------------------------|
+| `state$`     | `SignalFn<TState>`     | Реактивный сигнал текущего состояния. Обновляется при каждом `set()`.        |
+| `completed$` | `Subject<void>`        | Срабатывает один раз при удалении записи. Используется для очистки подписок. |
+
+
+## Методы
+
+| Метод      | Параметры      | Возвращаемое значение | Описание                                              |
+|------------|----------------|-----------------------|-------------------------------------------------------|
+| `peek`     | —              | `TState`              | Синхронный снимок состояния без реактивной подписки.  |
+| `set`      | `state: TState`| `void`                | Обновляет состояние. Игнорируется после `complete()`. |
+| `complete` | —              | `void`                | Завершает жизненный цикл.                             |
+
+
+## См. также
+
+- [CacheMap — API](./_CacheMap.md) — контейнер, хранящий записи кэша по ключам
+- [QueryCacheEntry — API](./_QueryCacheEntry.md) — расширение CacheEntry для query-слоя
+- [Кэш (концепция)](../concepts/cache.md) — общая архитектура кэша
+- [Машина состояний](../concepts/machine.md) — жизненный цикл состояния записи
+- [Архитектура](../concepts/architecture.md) — обзор архитектуры query-модуля

package/docs/query/api/_CacheMap.md

@@ -0,0 +1,30 @@
+# CacheMap — API
+
+Простой контейнер, мапящий значения на записи кэша.
+
+
+## Создание
+
+```ts
+const cacheMap = new CacheMap<TValue>();
+```
+
+## Методы
+
+| Метод         | Параметры                              | Возвращаемое значение       | Описание                                                                                |
+|---------------|----------------------------------------|-----------------------------|-----------------------------------------------------------------------------------------|
+| `get`         | `key: string`                          | `TValue \| undefined`       | Возвращает запись по ключу. Если записи нет, возвращает `undefined`.                    |
+| `set`         | `key: string, value: TValue`           | `void`                      | Устанавливает запись по ключу.                                                          |
+| `delete`      | `key: string`                          | `boolean`                   | Удаляет запись по ключу. Возвращает `true`, если запись была удалена, иначе `false`.    |
+| `has`         | `key: string`                          | `boolean`                   | Проверяет наличие записи.                                                               |
+| `clear`       | —                                      | `void`                      | Удаляет все записи.                                                                     |
+| `size`        | —                                      | `number` (readonly)         | Количество записей.                                                                     |
+| `values`      | —                                      | `IterableIterator<TEntry>`  | Итератор по всем записям.                                                               |
+
+
+## См. также
+
+- [CacheEntry — API](./_CacheEntry.md) — базовый реактивный контейнер записи кэша
+- [QueryCacheEntry — API](./_QueryCacheEntry.md) — расширение CacheEntry для query-слоя
+- [Кэш (концепция)](../concepts/cache.md) — общая архитектура кэша
+- [Архитектура](../concepts/architecture.md) — обзор архитектуры query-модуля

package/docs/query/api/_QueryCacheEntry.md

@@ -0,0 +1,81 @@
+# Запись кэша запроса (QueryCacheEntry) — API
+
+Расширяет [CacheEntry][cache-entry-api], 
+    добавляя жизненный цикл запроса: выполнение `queryFn`, 
+    дедупликация, прерывание, [патчинг][patching-concept] 
+    и интеграция с [машиной состояний][machine-concept]. 
+Используется [ресурсом][resource-api] и [командой][command-api].
+
+
+## Опции
+
+| Опция                | Тип                                                                | По умолчанию        | Описание                                                                                                |
+|----------------------|--------------------------------------------------------------------|---------------------|---------------------------------------------------------------------------------------------------------|
+| `queryFn`            | `(keyedArgs: Keyed<TArgs>, signal: AbortSignal) => Promise<TData>` | (Обязательное поле) | Функция для получения данных. Принимает аргументы и сигнал прерывания.                                  |
+| `retentionTime`      | `number \| false`                                                  | (Обязательное поле) | Время (мс) удержания записи после отписки последнего подписчика. `false` — не удалять.                  |
+| `keyedArgs`          | `Keyed<TArgs>`                                                     | (Обязательное поле) | Аргументы для `queryFn`. Используются для дедупликации и отображения в DevTools.                        |
+| `resourceKey`        | `string`                                                           | —                   | Ключ для отображения в DevTools.                                                                        |
+| `initialMachine`     | `IMachine<TArgs, TData>`                                           | —                   | Машина состояний для инициализации записи.                                                              |
+| `beforeDevtoolsPush` | `(state: TState) => TState`                                        | —                   | Функция для изменения состояния перед отправкой в DevTools. Полезно для удаления чувствительных данных. |
+
+
+## Свойства
+
+| Свойство   | Тип                                          | Описание                                                    |
+|------------|----------------------------------------------|-------------------------------------------------------------|
+| `keyedArgs` | `Keyed<TArgs>`                              | Аргументы, с которыми была создана запись.                  |
+| `machine$` | `SignalFn<TMachineInstance<TArgs, TData>>`   | Реактивный сигнал состояния [машины][machine-concept]. |
+
+> Наследуемые свойства `state$`, `completed$` — см. [CacheEntry][cache-entry-api].
+
+
+## Методы
+
+| Метод         | Параметры                     | Возвращаемое значение | Описание                                                            |
+|---------------|-------------------------------|-----------------------|---------------------------------------------------------------------|
+| `refresh`     | —                             | `void`                | Переводит запись в `refreshing` и перезапрашивает данные. |
+| `retry`       | —                             | `void`                | Перезапускает запрос после ошибки.                                         |
+| `createPatch` | `patchFn: (data: TData) => void` | `IPatchHandle \| null` | Создаёт оптимистичный. См. [Патчинг][patching-section].             |
+
+
+> Наследуемые `peek()`, `set()`, `complete()` — см. [CacheEntry][cache-entry-api].
+
+
+## Выполнение запроса
+
+При создании записи `queryFn` вызывается автоматически, если `initialState` **не** было указано.
+
+Принудительный запрос (`refresh()`) прерывает текущий запрос через `AbortSignal` и запускает новый.
+
+Если результат приходит от уже прерванного запроса (stale-check),
+    он игнорируется — запись принимает только данные от актуального запроса.
+
+
+> Запись может быть инициализирована из снапшота — например, при [кросс-табовой синхронизации][broadcast-usage] или при восстановлении состояния.
+
+
+## Патчинг
+
+Подробности — см. [патчинг][patching-concept].
+
+
+## См. также
+
+- [CacheEntry — API][cache-entry-api]
+- [CacheMap — API][cache-map-api]
+- [Машина состояний][machine-concept]
+- [Патчинг][patching-concept]
+- [Ресурс — API][resource-api]
+- [Команда — API][command-api]
+
+---
+
+[cache-entry-api]: ./_CacheEntry.md
+[cache-map-api]: ./_CacheMap.md
+[machine-concept]: ../concepts/machine.md
+[patching-concept]: ../concepts/patching.md
+[resource-api]: ./resource.md
+[command-api]: ./command.md
+[query-execution]: #выполнение-запроса
+[patching-section]: #патчинг
+[broadcast-usage]: ../usage/broadcast.md

package/docs/query/api/command-agent.md

@@ -0,0 +1,60 @@
+# Агент команды (CommandAgent) — API
+
+Агент команды — реактивный наблюдатель, транслирующий состояние [записи кэша][cache] команды в плоский сигнал. В отличие от [агента ресурса][resource-agent], агент команды не поддерживает SKIP и SWR-fallback — мутации запускаются явно через `trigger`. Концепция и жизненный цикл описаны в [concepts/agent.md][agent-concept].
+
+
+## Создание
+
+```typescript
+const agent = addTodoCommand.createAgent({ key: 'my-mutation-1' });
+```
+
+Метод `createAgent()` доступен у каждой [команды][api-cmd]. Принимает опциональный объект с полем `key` — строковый идентификатор кэш-записи, за которой агент будет наблюдать.
+
+
+## Методы
+
+| Метод | Сигнатура | Описание |
+|-------|-----------|----------|
+| `state$` | `() => TCommandAgentState<TArgs, TData>` | Вычисляемый сигнал. Возвращает текущее состояние агента. |
+| `trigger` | `(args: TArgs, key?: string) => Promise<TData>` | Запускает мутацию с указанными аргументами. Необязательный `key` переключает агент на другую кэш-запись перед выполнением. Возвращает промис с результатом. |
+| `setKey` | `(key: string) => void` | Переключает наблюдение на другую кэш-запись по ключу. |
+
+
+## Состояние (TCommandAgentState)
+
+| Поле | Тип                                           | Описание |
+|------|-----------------------------------------------|----------|
+| `status` | `"idle" \| "pending" \| "success" \| "error"` | Текущий статус агента. |
+| `data` | `TData \| null`                               | Данные результата мутации. `null` до завершения. |
+| `error` | `unknown`                                     | Ошибка мутации. `null` в `idle` / `pending` / `success`. |
+| `args` | `TArgs \| null`                               | Аргументы последнего вызова `trigger`. `null` в `idle`. |
+| `isLoading` | `boolean`                                     | `true`, пока мутация выполняется (`pending`). |
+| `isSuccess` | `boolean`                                     | `true`, если мутация завершилась успешно. |
+| `isError` | `boolean`                                     | `true`, если мутация завершилась ошибкой. |
+| `entry` | `QueryCacheEntry<TArgs, TData> \| null`      | Текущая запись кэша. `null` в `idle`. |
+
+
+## Статусы
+
+| Статус | `isLoading` | `isSuccess` | `isError` | Описание |
+|--------|:-----------:|:-----------:|:---------:|----------|
+| `idle` | — | — | — | Мутация не запускалась или ключ не привязан. |
+| `pending` | ✓ | — | — | Мутация выполняется. |
+| `success` | — | ✓ | — | Мутация завершилась успешно, данные доступны в `data`. |
+| `error` | — | — | ✓ | Мутация завершилась ошибкой. |
+
+
+## См. также
+
+- [Концепция агента][agent-concept] — жизненный цикл, SWR-fallback (только ресурсы)
+- [Агент ресурса — API][resource-agent] — аналог для операций чтения
+- [Команда — API][api-cmd] — создание команды и метод `createAgent()`
+- [Использование команд][usage-cmd] — хук `useCommand`, примеры, паттерны
+
+
+[agent-concept]: ../concepts/agent.md
+[resource-agent]: ./resource-agent.md
+[api-cmd]: ./command.md
+[usage-cmd]: ../usage/command.md
+[cache]: ../concepts/cache.md

package/docs/query/api/command.md

@@ -0,0 +1,76 @@
+# Команда (Command) — API
+
+Команда — абстракция для операций записи (мутаций). Примеры и паттерны — см. [руководство по использованию][usage].
+
+
+## Создание
+
+```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`            | `(args: TArgs) => Promise<TData>`            | **обязательный** | Функция выполнения мутации.                                                  |
+| `key`                | `string`                                     | —                | Префикс для ключей кэша и devtools.                                          |
+| `links`              | `(link) => void`                             | —                | Колбэк для описания связей с ресурсами. См. [links][usage-links].                        |
+| `retentionTime`      | `number \| false`                            | `0`              | Время (мс) удержания кэш-записи после потери подписчиков. `false` — не удалять. Переопределяет `commandRetentionTime` из [API][api-readme]. |
+| `onCacheEntryAdded`  | `(args, ctx) => void`                        | —                | Вызывается при создании кэш-записи. См. [lifecycle hooks][usage-lifecycle].  |
+| `onQueryStarted`     | `(args, ctx) => void \| Promise<void>`       | —                | Вызывается при каждом запуске `queryFn`. См. [lifecycle hooks][usage-lifecycle]. |
+| `sync`               | `boolean`                                    | `false`          | Включить/отключить [кросс-табовую синхронизацию][usage-broadcast]. По умолчанию выключена (`defaultSync: 'none'`). Для включения укажите `sync: true` на команде или `defaultSync: 'all'` на уровне API. Игнорируется, если `syncDriver` не задан в API. |
+
+
+## Методы
+
+| Метод         | Параметры           | Возвращаемое значение   | Описание                                                                     |
+|---------------|---------------------|-------------------------|------------------------------------------------------------------------------|
+| `trigger`     | `args: Args<TArgs>` | `Promise<TData>`    | Императивный запуск мутации. Необязательный `key` идентифицирует кэш-запись.  |
+| `createAgent` | `key?: string`      | `Agent`                 | Создаёт реактивный [агент][agent] — наблюдатель за командой. Необязательный ключ привязывает к кэш-записи. |
+| `getEntry`    | `key: string`       | `QueryCacheEntry \| null`    | Синхронно возвращает кэш-запись.                                             |
+| `getEntry$`   | `key: string`       | `QueryCacheEntry \| null`    | Реактивный аналог `getEntry` — для использования в реактивном контексте.     |
+
+
+## Расширения
+
+| Метод         | Параметры           | Возвращаемое значение   | Описание                                                                     |
+|---------------|---------------------|-------------------------|------------------------------------------------------------------------------|
+| `useCommand`  | `key?: string`      | `[trigger, TCommandState]` | React-хук. Требует `reactHooksPlugin()`. Подписывается на состояние мутации.|
+
+
+## См. также
+
+- [Использование команды][usage] — примеры, паттерны, links, lifecycle hooks
+- [Ресурс — API][resource-api] — API чтения данных
+- [Машина состояний запроса][machine] — переходы между статусами
+- [Агент][agent] — реактивный наблюдатель
+- [Агент команды — API][agent-api] — полная таблица методов и статусов агента
+- [Система кэширования][cache] — жизненный цикл записей кэша
+
+
+[cache]: ../concepts/cache.md
+[usage]: ../usage/command.md
+[usage-links]: ../usage/links.md
+[usage-lifecycle]: ../usage/lifecycle.md
+[resource-api]: ./resource.md
+[machine]: ../concepts/machine.md
+[agent]: ../concepts/agent.md
+[agent-api]: ./command-agent.md
+[api-readme]: ./README.md
+[usage-broadcast]: ../usage/broadcast.md

package/docs/query/api/resource-agent.md

@@ -0,0 +1,68 @@
+# Агент ресурса (ResourceAgent) — API
+
+Агент — реактивный наблюдатель, транслирующий состояние [записи кэша][cache] в плоский сигнал с SWR-поведением. Концепция, жизненный цикл и SWR-fallback описаны в [concepts/agent.md][agent-concept].
+
+
+## Создание
+
+```typescript
+const agent = usersResource.createAgent();
+```
+
+Метод `createAgent()` доступен у каждого [ресурса][api-res]. Агент создаётся без аргументов — наблюдение начинается после вызова `start()`.
+
+
+## Методы
+
+| Метод | Сигнатура | Описание                                                                                                               |
+|-------|-----------|------------------------------------------------------------------------------------------------------------------------|
+| `state$` | `() => TResourceAgentState<TArgs, TData>` | Вычисляемый сигнал. Возвращает текущее состояние агента.                                                               |
+| `start` | `() => void` | Начинает или переключает наблюдение за ресурсом с указанными аргументами. При передаче `SKIP` агент переходит в `idle`. |
+| `retry` | `() => void` | Повторяет последний запрос, при ошибке |                                                                                |
+| `refresh` | `() => void` | Принудительно обновляет данные, при ошибке сохраняет устаревшие данные. |
+| `set` | `(args: ArgsOrVoidOrSkip<TArgs>, mark: boolean) => void` | Устанавливает наблюдаемые args (не инициирует запрос) |
+
+
+## Состояние (TResourceAgentState)
+
+| Поле | Тип | Описание |
+|------|-----|----------|
+| `status` | `TMachineStatus \| "idle"` | Текущий статус агента. См. таблицу статусов ниже. |
+| `data` | `TData \| null` | Данные. При SWR-fallback содержит устаревшие данные предыдущей записи. |
+| `error` | `unknown` | Ошибка текущего запроса. `null` в `idle` / `success` / `pending`. |
+| `args` | `TArgs \| null` | Аргументы текущего наблюдения. `null` в `idle`. |
+| `isLoading` | `boolean` | `true` при любой загрузке (`pending` или `refreshing`). |
+| `isInitialLoading` | `boolean` | `true` только при первичной загрузке (`pending`). |
+| `isRefreshing` | `boolean` | `true` при фоновом обновлении (SWR). |
+| `isRefreshError` | `boolean` | `true`, если фоновое обновление завершилось ошибкой. |
+| `isSuccess` | `boolean` | `true`, если данные получены успешно. |
+| `isError` | `boolean` | `true`, если запрос завершился ошибкой. |
+| `entry` | `IResourceCacheEntry<TArgs, TData> \| null` | Текущая запись кэша. `null` в `idle`. |
+| `retry` | `() => void` | Метод для повторного запроса, при ошибке. |
+| `refresh` | `() => void` | Метод для принудительного обновления данных. |
+
+## Статусы
+
+| Статус | `isLoading` | `isInitialLoading` | `isRefreshing` | `isRefreshError` | `isSuccess` | `isError` | Описание |
+|--------|:-----------:|:-------------------:|:--------------:|:-----------------:|:-----------:|:---------:|----------|
+| `idle` | — | — | — | — | — | — | Передан `SKIP`, наблюдение не активно. |
+| `pending` | ✓ | ✓ | — | — | — | — | Первичный запрос в процессе. |
+| `success` | — | — | — | — | ✓ | — | Данные получены. |
+| `error` | — | — | — | — | — | ✓ | Запрос завершился ошибкой. |
+| `refreshing` | ✓ | — | ✓ | — | — | — | Фоновое обновление; устаревшие данные доступны через `data`. |
+| `refresh-error` | — | — | — | ✓ | — | ✓ | Фоновое обновление завершилось ошибкой; устаревшие данные сохранены. |
+
+
+## См. также
+
+- [Концепция агента][agent-concept] — SWR-fallback, SKIP, жизненный цикл
+- [Ресурс — API][api-res] — создание ресурса и метод `createAgent()`
+- [Использование ресурса][usage-res] — хук `useResource`, примеры, паттерны
+- [Машина состояний][machine] — переходы между статусами записи кэша
+
+
+[agent-concept]: ../concepts/agent.md
+[api-res]: ./resource.md
+[usage-res]: ../usage/resource.md
+[machine]: ../concepts/machine.md
+[cache]: ../concepts/cache.md

package/docs/query/api/resource.md

@@ -0,0 +1,77 @@
+# Ресурс (Resource) — API
+
+Ресурс — абстракция для чтения данных с кэшированием и SWR. Примеры и паттерны — см. [руководство по использованию][usage].
+
+
+## Создание
+
+```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();
+    },
+    key: 'users',
+});
+```
+
+
+## Опции
+
+| Опция               | Тип                                                         | По умолчанию      | Описание                                                            |
+|----------------------|-------------------------------------------------------------|-------------------|---------------------------------------------------------------------|
+| `queryFn`            | `(args: TArgs, abortSignal: AbortSignal) => Promise<TData>` | **обязательный**  | Функция запроса данных.                                             |
+| `key`                | `string`                                                    | —                 | Префикс для ключей кэша и devtools.                                 |
+| `retentionTime`      | `number \| false`                                           | `60_000`          | Время (мс) удержания записи после потери подписчиков. `false` — не удалять. Переопределяет `resourceRetentionTime` из [API][api-readme]. |
+| `serializeArgs`      | `(args: TArgs) => string`                                   | `stableStringify` | Сериализация аргументов в кэш-ключ.                                 |
+| `onCacheEntryAdded`  | `(args, ctx) => void`                                       | —                 | Вызывается при создании кэш-записи. См. [lifecycle hooks][usage-lifecycle]. |
+| `onQueryStarted`     | `(args, ctx) => void \| Promise<void>`                      | —                 | Вызывается при каждом запуске `queryFn`. См. [lifecycle hooks][usage-lifecycle]. |
+| `sync`               | `boolean`                                                   | `false`           | Включить/отключить [кросс-табовую синхронизацию][usage-broadcast]. Игнорируется, если `syncDriver` не задан в API. |
+| `getDevtoolsKey`     | `(args: Keyed<TArgs>) => string`                            | —                 | Ключ аргументов для отображения в DevTools.                            |
+
+
+### Опции класса (Resource)
+
+| Опция         | Тип                                                     | По умолчанию | Описание                   |
+|---------------|---------------------------------------------------------|--------------|----------------------------|
+| `beforeQuery` | `(args: Keyed<TArgs>) => Promise<TData \| typeof NONE>` | —            | Вызывается перед `queryFn` |
+
+## Методы
+
+| Метод          | Параметры                                     | Возвращаемое значение     | Описание                                                                                                                             |
+|----------------|-----------------------------------------------|---------------------------|--------------------------------------------------------------------------------------------------------------------------------------|
+| `trigger`        | `args: Args<TArgs>, doForce = false`          | `void`                    | Запускает запрос с заданными аргументами. При `doForce = false` (по умолчанию) перезапрос для существующей записи кэша не делает. |
+| `refresh`      | `args: Args<TArgs>`                           | `void`                    | Помечает запись как устаревшую и запускает фоновый перезапрос (SWR).                                                                 |
+| `getEntry`     | `args: ArgsOrVoid<TArgs>, doInitiate = false`       | `QueryCacheEntry \| null` | Синхронно возвращает кэш-запись.                                                                                                     |
+| `getEntry$`    | `args: ArgsOrVoid<TArgs>, doInitiate = false` | `QueryCacheEntry \| null`      | Реактивный аналог `getEntry` — для использования в реактивном контексте.                                                             |
+| `createAgent`  | —                                             | `Agent<TArgs, TData>`     | Создаёт реактивный [агент][agent] — наблюдатель за ресурсом с SWR-поведением.                                                        |
+| `serialize`    | `args: Args<TArgs>`                           | `string`                  | Возвращает строковый ключ кэша для заданных аргументов.                                                                              |
+| `toKeyed`      | `args: Args<TArgs>`                           | `Keyed<TArgs>`            | Оборачивает аргументы в пару `{ value, key }` — для передачи в методы, минуя повторную сериализацию.                                 |
+| `_getOrCreate` | `args: Args<TArgs>, doForce = false`          | `CacheEntry`              | Внутренний метод. Получает существующую или создаёт новую запись кэша для аргументов.                                                |
+
+### Расширения
+
+| Метод          | Параметры                                      | Возвращаемое значение   | Описание                                                                       |
+|----------------|------------------------------------------------|-------------------------|--------------------------------------------------------------------------------|
+| `useResource`  | `args: ArgsOrVoidOrSkip<TArgs>` | `TResourceState<TData>` | React-хук. Требует `reactHooksPlugin()`. Подписывается на данные.              |
+
+
+## См. также
+
+- [Использование ресурса][usage] — примеры, паттерны, состояния
+- [Команда — API][command-api] — API мутаций
+- [Машина состояний запроса][machine] — переходы между статусами
+- [Агент][agent] — реактивный наблюдатель
+- [Агент ресурса — API][agent-api] — полная таблица методов и статусов агента
+- [Типизация аргументов (Keyed)][keyed] — пайплайн аргументов: Args → Keyed → key
+
+
+[usage]: ../usage/resource.md
+[usage-lifecycle]: ../usage/lifecycle.md
+[command-api]: ./command.md
+[machine]: ../concepts/machine.md
+[agent]: ../concepts/agent.md
+[agent-api]: ./resource-agent.md
+[api-readme]: ./README.md
+[usage-broadcast]: ../usage/broadcast.md
+[keyed]: ../concepts/keyed.md

package/docs/query/concepts/agent.md

@@ -0,0 +1,70 @@
+# Агент
+
+Агент — SWR-наблюдатель, связывающий UI-компонент с [записью кэша][cache]. Он отслеживает текущую запись, транслирует её состояние в плоский реактивный сигнал и управляет переходами при смене аргументов. Агент используется как [ресурсами][usage-res], так и [командами][usage-cmd] — хуки `useResource` и `useCommand` создают его автоматически.
+
+## SKIP и состояние idle
+
+Специальный символ `SKIP` передаётся вместо аргументов, когда запрос выполнять не нужно — например, пока зависимые данные ещё не готовы. Агент переходит в состояние `idle`: запись кэша не создаётся, сетевой запрос не выполняется.
+
+## SWR-fallback при смене аргументов
+
+Агент хранит два слота: **текущая** и **предыдущая** запись. При смене аргументов:
+
+1. Если предыдущая запись содержит данные (`success` / `refreshing`/`refresh-error`), агент сохраняет их как устаревшие.
+2. Пока новая запись в `pending`, агент отдаёт устаревшие данные и выставляет статус `refreshing`. При `error` данные из предыдущей записи остаются доступны, но статус — `error`.
+3. Как только новая запись разрешается `success` — предыдущий слот очищается.
+
+Благодаря этому UI показывает предыдущие данные вместо пустого состояния, пока новый запрос загружается.
+
+## Статусы
+
+Агент предоставляет шесть статусов:
+
+- **idle** — передан `SKIP`, наблюдение не активно.
+- **pending** — первичный запрос в процессе.
+- **success** — данные получены.
+- **error** — запрос завершился ошибкой.
+- **refreshing** — фоновое обновление (SWR); устаревшие данные доступны. Как состояние машины — только у ресурсов (через `refresh()`). Как статус агента — также при SWR-маскировании (`pending` + предыдущие данные).
+- **refresh-error** — фоновое обновление завершилось ошибкой; устаревшие данные сохранены. Только для ресурсов.
+
+Статус `refresh-error` — это полноценное состояние [машины состояний][machine] (переход `refreshing → refresh-error` при ошибке фонового обновления). Агент транслирует его напрямую, без трансформации.
+
+Булевые флаги и полная таблица соответствий описаны в руководствах по [ресурсам][usage-res] и [командам][usage-cmd].
+
+Подробные sequence-диаграммы потоков (cache miss, cache hit, refresh, SWR-fallback и др.) — в [dataflows.md][dataflows].
+
+## Матрица состояний
+
+| Состояние машины | Статус агента | data | Описание поведения |
+|---|---|---|---|
+| _(нет записи / SKIP)_ | `idle` | `null` | Запрос не выполняется |
+| `pending` | `pending` | `null` | Ожидание первого ответа |
+| `pending` + _previous_ | `refreshing` | stale data из prev | SWR: pending маскируется в refreshing; stale данные показываются, пока новая запись загружается |
+| `success` | `success` | `TData` | Данные получены |
+| `error` | `error` | `null` | Ошибка, данных нет |
+| `error` + _previous_ | `error` | stale data из prev | Ошибка; stale данные из prev доступны, но статус — error |
+| `refreshing` | `refreshing` | stale `TData` | Фоновое обновление, показываются устаревшие данные (только ресурс) |
+| `refresh-error` | `refresh-error` | stale `TData` | Обновление завершилось ошибкой, стейл данные сохраняются (только ресурс) |
+
+Подробнее о механизме слотов — в разделе [SWR-fallback при смене аргументов][swr-fallback].
+
+## См. также
+
+- [Потоки данных][dataflows] — диаграммы всех ресурсных и командных потоков.
+- [Машина состояний][machine] — состояние, которое агент транслирует из записи кэша.
+- [Кэш][cache] — хранилище записей, за которыми наблюдает агент.
+- [Использование ресурсов][usage-res] — хук `useResource` и полная таблица состояний.
+- [Использование команд][usage-cmd] — хук `useCommand` и жизненный цикл мутаций.
+- [API: createResource][api-res] — создание ресурса и его агента.
+- [API: createCommand][api-cmd] — создание команды и её агента.
+
+---
+
+[swr-fallback]: #swr-fallback-при-смене-аргументов
+[machine]: machine.md
+[cache]: cache.md
+[dataflows]: dataflows.md
+[usage-res]: ../usage/resource.md
+[usage-cmd]: ../usage/command.md
+[api-res]: ../api/resource.md
+[api-cmd]: ../api/command.md