@itd-api/cache 0.0.1 → 0.1.0

package/README.md

@@ -3,12 +3,18 @@
 TTL/LRU-кэш и дедупликация одновременных запросов для
 [`itd-api`](https://github.com/KiowDev/itd-api).
 
+[Руководство](https://kiowdev.github.io/itd-api/packages/cache) ·
+[API из TSDoc](https://kiowdev.github.io/itd-api/api/generated/cache/)
+
 ## Установка
 
 ```bash
 npm install itd-api @itd-api/cache
 ```
 
+Поддерживается `itd-api >=0.5.0 <1.0.0`: cache использует namespace
+`RequestOptions.extensions` и стабильный `operationId` запроса.
+
 ## Быстрый старт
 
 ```ts
@@ -18,7 +24,7 @@ import { ItdClient } from 'itd-api';
 const itd = new ItdClient({ auth: process.env.ITD_TOKEN });
 const cached = cache({
   ttl: 60_000,
-  routes: ['users.get', 'posts.get', 'posts.list'],
+  operations: ['users.get', 'posts.get', 'posts.list'],
 });
 
 itd.use(cached);
@@ -27,16 +33,20 @@ const first = await itd.posts.get(postId);  // запрос к API
 const second = await itd.posts.get(postId); // ответ из кэша
 ```
 
-Кэшируются только перечисленные маршруты. Query, path и body входят в ключ, поэтому
+Кэшируются только перечисленные операции. Query, path и body входят в ключ, поэтому
 разные страницы ленты, профили и наборы идентификаторов хранятся отдельно. Одинаковые
 запросы, запущенные одновременно, выполняют один сетевой вызов.
 
+Имена в `operations` — стабильные `operationId`, а не HTTP-пути. Поэтому перенос endpoint не ломает
+правила кэша. Низкоуровневый `itd.request()` без явного ID считается операцией `raw`: одно лишь
+совпадение его URL со встроенным resource не включает кэш автоматически.
+
 ## Настройки
 
 ```ts
 const cached = cache({
   ttl: 60_000,
-  routes: ['users.get', 'posts.get'],
+  operations: ['users.get', 'posts.get'],
   maxEntries: 500,
   deduplicate: true,
 });
@@ -45,7 +55,7 @@ const cached = cache({
 | Поле | Значение |
 |---|---|
 | `ttl` | срок хранения успешного ответа в миллисекундах |
-| `routes` | операции, ответы которых нужно кэшировать |
+| `operations` | операции, ответы которых нужно кэшировать |
 | `maxEntries` | предел LRU-кэша; по умолчанию `500` |
 | `deduplicate` | объединение одновременных запросов; по умолчанию `true` |
 
@@ -55,8 +65,8 @@ const cached = cache({
 ## Управление отдельным запросом
 
 ```ts
-await itd.posts.get(postId, { cache: 'reload' });
-await itd.posts.get(postId, { cache: 'no-store' });
+await itd.posts.get(postId, { extensions: { cache: 'reload' } });
+await itd.posts.get(postId, { extensions: { cache: 'no-store' } });
 ```
 
 - `reload` пропускает готовый ответ, запрашивает новый и заменяет запись;
@@ -68,11 +78,12 @@ await itd.posts.get(postId, { cache: 'no-store' });
 
 ## Инвалидация
 
-После успешной мутации плагин удаляет связанные читающие маршруты. Например, реакция на
+После успешной мутации плагин удаляет связанные читающие операции. Например, реакция на
 пост сбрасывает кэш постов и статистики, но не затрагивает профили, файлы и настройки
-платформы. Маршруты с общими данными инвалидируются во всех разделах экземпляра: изменение
-поста одним аккаунтом должно быть видно остальным. Персональные настройки, уведомления и
-сессии затрагивают только свой раздел.
+платформы. Операции с общими данными инвалидируются во всех аккаунтах экземпляра: изменение
+поста одним аккаунтом должно быть видно остальным. Персональные настройки и уведомления
+инвалидируются у всех копий клиента с тем же пользователем. Изменение сессий сбрасывает все
+варианты `auth.sessions` этого аккаунта, включая варианты других сессий.
 
 Известные запросы без зависимостей, включая telemetry и создание жалобы, кэш не меняют.
 
@@ -85,7 +96,7 @@ cached.invalidate('posts.get', 'posts.list');
 cached.clear();
 ```
 
-`invalidate()` удаляет все варианты выбранных маршрутов во всех подключённых клиентах.
+`invalidate()` удаляет все варианты выбранных операций во всех подключённых клиентах.
 `clear()` очищает всё хранилище. Оба метода защищены от гонки: запрос, начатый до очистки,
 не запишет устаревший результат после неё.
 
@@ -102,9 +113,13 @@ detachCache();
 stream.disconnect();
 ```
 
-Привязка сразу очищает `notifications.list` и `notifications.count`. Новое уведомление
-сбрасывает оба маршрута, событие `unreadCount` — счётчик. Другие разделы кэша поток не
-изменяет.
+Привязка сразу очищает `notifications.list` и `notifications.count` аккаунта, который
+создал поток. Новое уведомление сбрасывает обе операции во всех копиях клиента с тем же
+пользователем, событие `unreadCount` — их счётчик. Кэш других аккаунтов и остальные операции
+поток не изменяет.
+
+У стороннего realtime-объекта без доступных идентификатора пользователя и базового URL
+используется безопасный fallback: операции уведомлений инвалидируются во всех аккаунтах.
 
 ## Несколько клиентов
 
@@ -125,21 +140,26 @@ clientB.use(shared);
 // либо accounts.use(shared)
 ```
 
-Каждая установка получает собственный раздел. Ответы и одновременные запросы разных
-клиентов не пересекаются: даже публичные профили и посты содержат персонализированные
-поля `isLiked`, `isFollowing` и `isReposted`. Инвалидация общей сущности применяется ко
-всем разделам, а персонального состояния — только к клиенту, который его изменил.
+Копии клиента с одинаковыми базовым URL и пользователем используют общий раздел: готовые
+ответы и одновременные запросы между ними объединяются. Это безопасно для персонализированных
+полей `isLiked`, `isFollowing` и `isReposted`, потому что их значения принадлежат аккаунту,
+а не конкретному access token.
+
+Разные пользователи изолированы. Только `auth.sessions` дополнительно разделяется по сессии,
+поскольку ответ отмечает текущую серверную сессию. Если идентификаторов пользователя или
+сессии в токене нет, плагин использует безопасный уникальный раздел установки и ничего между
+копиями не объединяет.
 
-`maxEntries` ограничивает весь экземпляр `shared`, а `clear()`, `invalidate()` и
-`attachRealtime()` управляют всеми его разделами. При `setSession()`, входе или выходе
-раздел клиента меняется автоматически.
+`maxEntries` ограничивает весь экземпляр `shared`, а `clear()` и `invalidate()` управляют
+всеми его разделами. `attachRealtime()` затрагивает аккаунт создавшего поток клиента.
+Смена сессии сохраняет общий кэш, смена пользователя автоматически выбирает другой раздел.
 
 ## Ключ
 
 В ключ входят:
 
-- имя маршрута, HTTP-метод и path;
-- непрозрачная область клиента и его текущей сессии;
+- имя операции, HTTP-метод и path;
+- базовый URL и идентификатор пользователя; для `auth.sessions` также идентификатор сессии;
 - `service` или разовый `baseUrl`;
 - query и JSON-body;
 - режим `raw`, `skipAuth` и опции других плагинов, влияющие на ответ.
@@ -150,9 +170,9 @@ clientB.use(shared);
 Ответ хранится как независимая копия: изменение полученного объекта не меняет следующие
 результаты.
 
-## Доступные маршруты
+## Доступные операции
 
-| Раздел | Маршруты |
+| Раздел | Операции |
 |---|---|
 | Auth | `auth.sessions` |
 | Users | `users.me`, `users.get`, `users.checkUsername`, `users.search`, `users.whoToFollow`, `users.topClans`, `users.followers`, `users.following`, `users.blocked`, `users.getPrivacy`, `users.pins`, `users.followStatus` |
@@ -166,14 +186,14 @@ clientB.use(shared);
 | Verification | `verification.status` |
 | Platform | `platform.changelog`, `platform.announcements`, `platform.portal`, `platform.status` |
 
-Страницы, загружаемые итераторами, используют маршрут соответствующего списочного метода:
+Страницы, загружаемые итераторами, используют операцию соответствующего списочного метода:
 `posts.iterate()` — `posts.list`, `users.iterateFollowers()` — `users.followers` и так
 далее.
 
 Каталог доступен программно:
 
 ```ts
-import { CACHE_ROUTES } from '@itd-api/cache';
+import { CACHE_OPERATIONS } from '@itd-api/cache';
 
-console.log(CACHE_ROUTES.map(({ id }) => id));
+console.log(CACHE_OPERATIONS.map(({ id }) => id));
 ```