@itd-api/cache 0.0.2 → 0.2.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.8.0 <1.0.0`: пакет использует отдельное поле
+`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,24 @@ const first = await itd.posts.get(postId);  // запрос к API
 const second = await itd.posts.get(postId); // ответ из кэша
 ```
 
-Кэшируются только перечисленные маршруты. Query, path и body входят в ключ, поэтому
+Операции подключаемых модулей тоже можно кэшировать. Например, модуль Pixel Battle задаёт
+`CachePolicyKind.Query` в `annotations.cache`, а пользователь добавляет полный `operationId`
+в `operations`.
+
+Кэшируются только перечисленные операции. Query, path и body входят в ключ, поэтому
 разные страницы ленты, профили и наборы идентификаторов хранятся отдельно. Одинаковые
 запросы, запущенные одновременно, выполняют один сетевой вызов.
 
+Имена в `operations` — постоянные `operationId`, а не HTTP-пути. Изменение маршрута не ломает
+правила кэша. Низкоуровневый `itd.request()` без явного идентификатора операции считается
+операцией `raw`; совпадение URL со встроенным ресурсом не включает кэш автоматически.
+
 ## Настройки
 
 ```ts
 const cached = cache({
   ttl: 60_000,
-  routes: ['users.get', 'posts.get'],
+  operations: ['users.get', 'posts.get'],
   maxEntries: 500,
   deduplicate: true,
 });
@@ -45,7 +59,7 @@ const cached = cache({
 | Поле | Значение |
 |---|---|
 | `ttl` | срок хранения успешного ответа в миллисекундах |
-| `routes` | операции, ответы которых нужно кэшировать |
+| `operations` | операции, ответы которых нужно кэшировать |
 | `maxEntries` | предел LRU-кэша; по умолчанию `500` |
 | `deduplicate` | объединение одновременных запросов; по умолчанию `true` |
 
@@ -55,8 +69,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,9 +82,9 @@ await itd.posts.get(postId, { cache: 'no-store' });
 
 ## Инвалидация
 
-После успешной мутации плагин удаляет связанные читающие маршруты. Например, реакция на
+После успешной мутации плагин удаляет связанные читающие операции. Например, реакция на
 пост сбрасывает кэш постов и статистики, но не затрагивает профили, файлы и настройки
-платформы. Маршруты с общими данными инвалидируются во всех аккаунтах экземпляра: изменение
+платформы. Операции с общими данными инвалидируются во всех аккаунтах экземпляра: изменение
 поста одним аккаунтом должно быть видно остальным. Персональные настройки и уведомления
 инвалидируются у всех копий клиента с тем же пользователем. Изменение сессий сбрасывает все
 варианты `auth.sessions` этого аккаунта, включая варианты других сессий.
@@ -86,15 +100,15 @@ cached.invalidate('posts.get', 'posts.list');
 cached.clear();
 ```
 
-`invalidate()` удаляет все варианты выбранных маршрутов во всех подключённых клиентах.
+`invalidate()` удаляет все варианты выбранных операций во всех подключённых клиентах.
 `clear()` очищает всё хранилище. Оба метода защищены от гонки: запрос, начатый до очистки,
 не запишет устаревший результат после неё.
 
-## Realtime
+## События
 
 ```ts
-const stream = itd.realtime();
-const detachCache = cached.attachRealtime(stream);
+const stream = itd.notifications.events;
+const detachCache = cached.attachNotificationEvents(stream);
 
 await stream.connect();
 
@@ -104,12 +118,16 @@ stream.disconnect();
 ```
 
 Привязка сразу очищает `notifications.list` и `notifications.count` аккаунта, который
-создал поток. Новое уведомление сбрасывает оба маршрута во всех копиях клиента с тем же
-пользователем, событие `unreadCount` — их счётчик. Кэш других аккаунтов и остальные маршруты
+создал поток. Новое уведомление сбрасывает обе операции во всех копиях клиента с тем же
+пользователем, событие `unreadCount` — их счётчик. Кэш других аккаунтов и остальные операции
 поток не изменяет.
 
-У стороннего realtime-объекта без доступных идентификатора пользователя и базового URL
-используется безопасный fallback: маршруты уведомлений инвалидируются во всех аккаунтах.
+Инвалидация подключается как промежуточный обработчик. Вызывайте
+`attachNotificationEvents()` до прикладных обработчиков, которые могут не вызвать `next()`:
+тогда отфильтрованное для интерфейса обновление всё равно не оставит устаревший кэш.
+
+У стороннего событийного объекта без доступных идентификатора пользователя и базового URL
+операции уведомлений инвалидируются во всех аккаунтах.
 
 ## Несколько клиентов
 
@@ -141,28 +159,28 @@ clientB.use(shared);
 копиями не объединяет.
 
 `maxEntries` ограничивает весь экземпляр `shared`, а `clear()` и `invalidate()` управляют
-всеми его разделами. `attachRealtime()` затрагивает аккаунт создавшего поток клиента.
+всеми его разделами. `attachNotificationEvents()` затрагивает аккаунт создавшего поток клиента.
 Смена сессии сохраняет общий кэш, смена пользователя автоматически выбирает другой раздел.
 
 ## Ключ
 
 В ключ входят:
 
-- имя маршрута, HTTP-метод и path;
+- имя операции, HTTP-метод и path;
 - базовый URL и идентификатор пользователя; для `auth.sessions` также идентификатор сессии;
 - `service` или разовый `baseUrl`;
-- query и JSON-body;
+- параметры строки запроса и JSON-тело;
 - режим `raw`, `skipAuth` и опции других плагинов, влияющие на ответ.
 
 Токен и заголовки в ключ не входят. Также не учитываются `signal`, `timeout` и настройки
-повторов. Несериализуемый JSON-body выполняется без кэширования.
+повторов. Запрос с несериализуемым JSON-телом выполняется без кэширования.
 
 Ответ хранится как независимая копия: изменение полученного объекта не меняет следующие
 результаты.
 
-## Доступные маршруты
+## Доступные операции
 
-| Раздел | Маршруты |
+| Раздел | Операции |
 |---|---|
 | 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` |
@@ -174,16 +192,16 @@ clientB.use(shared);
 | Files | `files.get` |
 | Subscription | `subscription.status`, `subscription.methods` |
 | Verification | `verification.status` |
-| Platform | `platform.changelog`, `platform.announcements`, `platform.portal`, `platform.status` |
+| Platform | `platform.changelog`, `platform.announcements`, `platform.portal`, `status.get` |
 
-Страницы, загружаемые итераторами, используют маршрут соответствующего списочного метода:
+Страницы, загружаемые итераторами, используют операцию соответствующего списочного метода:
 `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));
 ```