@itd-api/cache 0.0.2 → 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,9 +78,9 @@ await itd.posts.get(postId, { cache: 'no-store' });
 
 ## Инвалидация
 
-После успешной мутации плагин удаляет связанные читающие маршруты. Например, реакция на
+После успешной мутации плагин удаляет связанные читающие операции. Например, реакция на
 пост сбрасывает кэш постов и статистики, но не затрагивает профили, файлы и настройки
-платформы. Маршруты с общими данными инвалидируются во всех аккаунтах экземпляра: изменение
+платформы. Операции с общими данными инвалидируются во всех аккаунтах экземпляра: изменение
 поста одним аккаунтом должно быть видно остальным. Персональные настройки и уведомления
 инвалидируются у всех копий клиента с тем же пользователем. Изменение сессий сбрасывает все
 варианты `auth.sessions` этого аккаунта, включая варианты других сессий.
@@ -86,7 +96,7 @@ cached.invalidate('posts.get', 'posts.list');
 cached.clear();
 ```
 
-`invalidate()` удаляет все варианты выбранных маршрутов во всех подключённых клиентах.
+`invalidate()` удаляет все варианты выбранных операций во всех подключённых клиентах.
 `clear()` очищает всё хранилище. Оба метода защищены от гонки: запрос, начатый до очистки,
 не запишет устаревший результат после неё.
 
@@ -104,12 +114,12 @@ stream.disconnect();
 ```
 
 Привязка сразу очищает `notifications.list` и `notifications.count` аккаунта, который
-создал поток. Новое уведомление сбрасывает оба маршрута во всех копиях клиента с тем же
-пользователем, событие `unreadCount` — их счётчик. Кэш других аккаунтов и остальные маршруты
+создал поток. Новое уведомление сбрасывает обе операции во всех копиях клиента с тем же
+пользователем, событие `unreadCount` — их счётчик. Кэш других аккаунтов и остальные операции
 поток не изменяет.
 
 У стороннего realtime-объекта без доступных идентификатора пользователя и базового URL
-используется безопасный fallback: маршруты уведомлений инвалидируются во всех аккаунтах.
+используется безопасный fallback: операции уведомлений инвалидируются во всех аккаунтах.
 
 ## Несколько клиентов
 
@@ -148,7 +158,7 @@ clientB.use(shared);
 
 В ключ входят:
 
-- имя маршрута, HTTP-метод и path;
+- имя операции, HTTP-метод и path;
 - базовый URL и идентификатор пользователя; для `auth.sessions` также идентификатор сессии;
 - `service` или разовый `baseUrl`;
 - query и JSON-body;
@@ -160,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` |
@@ -176,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));
 ```