@itd-api/cache 0.0.2 → 0.2.0

package/dist/index.d.ts

@@ -1,280 +1,222 @@
-import { RawRequestOptions, ItdPlugin, ItdRealtime, Unsubscribe } from 'itd-api';
-
-/** Ошибка настройки или использования плагина кэша. */
-declare class CacheError extends Error {
-    readonly name = "CacheError";
-}
-
-/** Описание читающего маршрута itd-api. */
-interface CacheRoute {
-    /** Публичное имя для настройки плагина. */
-    id: string;
-    /** Раздел клиента. */
-    category: string;
-    /** HTTP-метод маршрута. */
-    method: string;
-    /** Путь без query и базового URL. */
-    path: RegExp;
-}
-/**
- * Читающие маршруты, которые можно кэшировать.
- *
- * Порядок значим: точные служебные пути стоят перед динамическими маршрутами.
- */
-declare const CACHE_ROUTES: readonly [{
-    readonly id: "auth.sessions";
-    readonly category: "auth";
-    readonly method: "GET";
-    readonly path: RegExp;
-}, {
-    readonly id: "users.me";
-    readonly category: "users";
-    readonly method: "GET";
-    readonly path: RegExp;
-}, {
-    readonly id: "users.checkUsername";
-    readonly category: "users";
-    readonly method: "GET";
-    readonly path: RegExp;
-}, {
-    readonly id: "users.search";
-    readonly category: "users";
-    readonly method: "GET";
-    readonly path: RegExp;
-}, {
-    readonly id: "users.whoToFollow";
-    readonly category: "users";
-    readonly method: "GET";
-    readonly path: RegExp;
-}, {
-    readonly id: "users.topClans";
-    readonly category: "users";
-    readonly method: "GET";
-    readonly path: RegExp;
-}, {
-    readonly id: "users.followers";
-    readonly category: "users";
-    readonly method: "GET";
-    readonly path: RegExp;
-}, {
-    readonly id: "users.following";
-    readonly category: "users";
-    readonly method: "GET";
-    readonly path: RegExp;
-}, {
-    readonly id: "users.blocked";
-    readonly category: "users";
-    readonly method: "GET";
-    readonly path: RegExp;
-}, {
-    readonly id: "users.getPrivacy";
-    readonly category: "users";
-    readonly method: "GET";
-    readonly path: RegExp;
-}, {
-    readonly id: "users.pins";
-    readonly category: "users";
-    readonly method: "GET";
-    readonly path: RegExp;
-}, {
-    readonly id: "users.followStatus";
-    readonly category: "users";
-    readonly method: "POST";
-    readonly path: RegExp;
-}, {
-    readonly id: "users.get";
-    readonly category: "users";
-    readonly method: "GET";
-    readonly path: RegExp;
-}, {
-    readonly id: "posts.list";
-    readonly category: "posts";
-    readonly method: "GET";
-    readonly path: RegExp;
-}, {
-    readonly id: "posts.likedByUser";
-    readonly category: "posts";
-    readonly method: "GET";
-    readonly path: RegExp;
-}, {
-    readonly id: "posts.byUser";
-    readonly category: "posts";
-    readonly method: "GET";
-    readonly path: RegExp;
-}, {
-    readonly id: "posts.comments";
-    readonly category: "posts";
-    readonly method: "GET";
-    readonly path: RegExp;
-}, {
-    readonly id: "posts.stats";
-    readonly category: "posts";
-    readonly method: "POST";
-    readonly path: RegExp;
-}, {
-    readonly id: "posts.get";
-    readonly category: "posts";
-    readonly method: "GET";
-    readonly path: RegExp;
-}, {
-    readonly id: "comments.replies";
-    readonly category: "comments";
-    readonly method: "GET";
-    readonly path: RegExp;
-}, {
-    readonly id: "notifications.list";
-    readonly category: "notifications";
-    readonly method: "GET";
-    readonly path: RegExp;
-}, {
-    readonly id: "notifications.count";
-    readonly category: "notifications";
-    readonly method: "GET";
-    readonly path: RegExp;
-}, {
-    readonly id: "notifications.getSettings";
-    readonly category: "notifications";
-    readonly method: "GET";
-    readonly path: RegExp;
-}, {
-    readonly id: "hashtags.search";
-    readonly category: "hashtags";
-    readonly method: "GET";
-    readonly path: RegExp;
-}, {
-    readonly id: "hashtags.trending";
-    readonly category: "hashtags";
-    readonly method: "GET";
-    readonly path: RegExp;
-}, {
-    readonly id: "hashtags.posts";
-    readonly category: "hashtags";
-    readonly method: "GET";
-    readonly path: RegExp;
-}, {
-    readonly id: "search.all";
-    readonly category: "search";
-    readonly method: "GET";
-    readonly path: RegExp;
-}, {
-    readonly id: "files.get";
-    readonly category: "files";
-    readonly method: "GET";
-    readonly path: RegExp;
-}, {
-    readonly id: "subscription.status";
-    readonly category: "subscription";
-    readonly method: "GET";
-    readonly path: RegExp;
-}, {
-    readonly id: "subscription.methods";
-    readonly category: "subscription";
-    readonly method: "GET";
-    readonly path: RegExp;
-}, {
-    readonly id: "verification.status";
-    readonly category: "verification";
-    readonly method: "GET";
-    readonly path: RegExp;
-}, {
-    readonly id: "platform.changelog";
-    readonly category: "platform";
-    readonly method: "GET";
-    readonly path: RegExp;
-}, {
-    readonly id: "platform.announcements";
-    readonly category: "platform";
-    readonly method: "GET";
-    readonly path: RegExp;
-}, {
-    readonly id: "platform.portal";
-    readonly category: "platform";
-    readonly method: "GET";
-    readonly path: RegExp;
-}, {
-    readonly id: "platform.status";
-    readonly category: "platform";
-    readonly method: "GET";
-    readonly path: RegExp;
-}];
-/** Имя маршрута, доступное в `cache({ routes: … })`. */
-type CacheRouteId = (typeof CACHE_ROUTES)[number]['id'];
-/** Раздел маршрута. */
-type CacheRouteCategory = (typeof CACHE_ROUTES)[number]['category'];
-/** Проверяет публичное имя маршрута. */
-declare function isCacheRouteId(value: string): value is CacheRouteId;
-/** Находит читающий маршрут по HTTP-методу и пути. */
-declare function cacheRoute(method: string, path: string): (typeof CACHE_ROUTES)[number] | undefined;
-
-/**
- * Собирает ключ из значений, влияющих на адрес, тело или разобранный ответ.
- *
- * Заголовки и транспортные опции намеренно не входят. Если тело либо опция другого
- * плагина не сериализуются как JSON, запрос выполняется без кэша.
- */
-declare function buildCacheKey(route: CacheRouteId, request: RawRequestOptions): string | undefined;
-
+import { ClientPlugin, NotificationEventContext, NotificationEvents, OperationId, OperationRequestOptions, Unsubscribe } from "itd-api";
+//#region src/plugin.d.ts
 /** Режимы кэширования отдельного запроса. */
 declare const CacheModes: Readonly<{
-    /** Отдать свежий кэш, иначе выполнить запрос и сохранить ответ. */
-    readonly Default: "default";
-    /** Пропустить сохранённое значение, выполнить запрос и перезаписать кэш. */
-    readonly Reload: "reload";
-    /** Не читать и не писать кэш для этого запроса. */
-    readonly NoStore: "no-store";
+  /** Отдать свежий кэш, иначе выполнить запрос и сохранить ответ. */
+  readonly Default: "default";
+  /** Пропустить сохранённое значение, выполнить запрос и перезаписать кэш. */
+  readonly Reload: "reload";
+  /** Не читать и не писать кэш для этого запроса. */
+  readonly NoStore: "no-store";
 }>;
 /** Поведение кэша для отдельного запроса. */
 type CacheMode = (typeof CacheModes)[keyof typeof CacheModes];
 /** Настройки плагина. */
 interface CacheOptions {
-    /** Сколько миллисекунд хранить успешный ответ. */
-    ttl: number;
-    /** Какие операции itd-api кэшировать. */
-    routes: readonly CacheRouteId[];
-    /** Максимальное количество ответов. По умолчанию 500. */
-    maxEntries?: number | undefined;
-    /** Объединять ли одновременные одинаковые запросы. По умолчанию `true`. */
-    deduplicate?: boolean | undefined;
+  /** Сколько миллисекунд хранить успешный ответ. */
+  ttl: number;
+  /** Какие операции itd-api кэшировать. */
+  operations: readonly OperationId[];
+  /** Максимальное количество ответов. По умолчанию 500. */
+  maxEntries?: number | undefined;
+  /** Объединять ли одновременные одинаковые запросы. По умолчанию `true`. */
+  deduplicate?: boolean | undefined;
 }
 /** Плагин и управление созданным им хранилищем. */
-interface CachePlugin extends ItdPlugin {
-    /** Количество готовых ответов во всех разделах кэша. */
-    readonly size: number;
-    /** Удаляет все ответы и не даёт выполняющимся запросам вернуть устаревший результат. */
-    clear(): void;
-    /** Удаляет все варианты названных маршрутов во всех подключённых клиентах. */
-    invalidate(...routes: CacheRouteId[]): void;
-    /**
-     * Очищает список и счётчик уведомлений по событиям realtime.
-     *
-     * Сразу удаляет прежние значения и возвращает функцию отписки.
-     */
-    attachRealtime(stream: ItdRealtime): Unsubscribe;
+interface CachePlugin extends ClientPlugin {
+  /** Количество готовых ответов во всех разделах кэша. */
+  readonly size: number;
+  /** Удаляет все ответы и не даёт выполняющимся запросам вернуть устаревший результат. */
+  clear(): void;
+  /** Удаляет все варианты названных операций во всех подключённых клиентах. */
+  invalidate(...operations: OperationId[]): void;
+  /**
+   * Подключает инвалидацию к нормализованным событиям уведомлений.
+   *
+   * Удаляет сохранённые список и счётчик, затем отслеживает обновления через промежуточный
+   * обработчик. Подключайте его до обработчиков, способных остановить цепочку.
+   */
+  attachNotificationEvents<C extends NotificationEventContext>(stream: NotificationEvents<C>): Unsubscribe;
 }
-/** Создаёт TTL/LRU-кэш разобранных ответов itd-api. */
+/** Создаёт TTL/LRU-кэш нормализованных результатов itd-api. */
 declare function cache(options: CacheOptions): CachePlugin;
-
+//#endregion
+//#region src/policy.d.ts
+/** Виды политики кэша, объявляемой в метаданных операции. */
+declare const CachePolicyKind: Readonly<{
+  readonly Query: "query";
+  readonly Mutation: "mutation";
+}>;
+type CachePolicyKind = (typeof CachePolicyKind)[keyof typeof CachePolicyKind];
+/** Области изоляции данных кэша. */
+declare const CachePolicyScope: Readonly<{
+  readonly Account: "account";
+  readonly Session: "session";
+}>;
+type CachePolicyScope = (typeof CachePolicyScope)[keyof typeof CachePolicyScope];
+/** Способы инвалидации кэша после мутации. */
+declare const CacheInvalidation: Readonly<{
+  readonly All: "all";
+}>;
+type CacheInvalidation = (typeof CacheInvalidation)[keyof typeof CacheInvalidation];
+//#endregion
+//#region src/errors.d.ts
+/** Ошибка настройки или использования плагина кэша. */
+declare class CacheError extends Error {
+  readonly name = "CacheError";
+}
+//#endregion
+//#region src/key.d.ts
 /**
- * `@itd-api/cache` — TTL/LRU-кэш и дедупликация запросов для itd-api.
- *
- * @example
- * ```ts
- * import { cache } from '@itd-api/cache';
- *
- * itd.use(cache({
- *   ttl: 60_000,
- *   routes: ['users.get', 'posts.get', 'posts.list'],
- * }));
- * ```
+ * Собирает ключ из значений, влияющих на адрес, тело или разобранный ответ.
  *
- * @packageDocumentation
+ * Заголовки и транспортные опции намеренно не входят. Если тело либо опция другого
+ * плагина не сериализуются как JSON, запрос выполняется без кэша.
  */
-
+declare function buildCacheKey(operation: OperationId, request: OperationRequestOptions): string | undefined;
+//#endregion
+//#region src/operations.d.ts
+/** Описание читающей операции itd-api. */
+interface CacheOperation {
+  /** Стабильный ID операции и публичное имя для настройки плагина. */
+  id: OperationId;
+  /** Раздел клиента. */
+  category: string;
+}
+/** Читающие операции, которые можно кэшировать. */
+declare const CACHE_OPERATIONS: readonly [Readonly<{
+  readonly id: "auth.sessions";
+  readonly category: "auth";
+}>, Readonly<{
+  readonly id: "users.me";
+  readonly category: "users";
+}>, Readonly<{
+  readonly id: "users.checkUsername";
+  readonly category: "users";
+}>, Readonly<{
+  readonly id: "users.search";
+  readonly category: "users";
+}>, Readonly<{
+  readonly id: "users.whoToFollow";
+  readonly category: "users";
+}>, Readonly<{
+  readonly id: "users.topClans";
+  readonly category: "users";
+}>, Readonly<{
+  readonly id: "users.followers";
+  readonly category: "users";
+}>, Readonly<{
+  readonly id: "users.following";
+  readonly category: "users";
+}>, Readonly<{
+  readonly id: "users.blocked";
+  readonly category: "users";
+}>, Readonly<{
+  readonly id: "users.getPrivacy";
+  readonly category: "users";
+}>, Readonly<{
+  readonly id: "users.pins";
+  readonly category: "users";
+}>, Readonly<{
+  readonly id: "users.followStatus";
+  readonly category: "users";
+}>, Readonly<{
+  readonly id: "users.get";
+  readonly category: "users";
+}>, Readonly<{
+  readonly id: "posts.list";
+  readonly category: "posts";
+}>, Readonly<{
+  readonly id: "posts.likedByUser";
+  readonly category: "posts";
+}>, Readonly<{
+  readonly id: "posts.byUser";
+  readonly category: "posts";
+}>, Readonly<{
+  readonly id: "posts.comments";
+  readonly category: "posts";
+}>, Readonly<{
+  readonly id: "posts.stats";
+  readonly category: "posts";
+}>, Readonly<{
+  readonly id: "posts.get";
+  readonly category: "posts";
+}>, Readonly<{
+  readonly id: "comments.replies";
+  readonly category: "comments";
+}>, Readonly<{
+  readonly id: "notifications.list";
+  readonly category: "notifications";
+}>, Readonly<{
+  readonly id: "notifications.count";
+  readonly category: "notifications";
+}>, Readonly<{
+  readonly id: "notifications.getSettings";
+  readonly category: "notifications";
+}>, Readonly<{
+  readonly id: "hashtags.search";
+  readonly category: "hashtags";
+}>, Readonly<{
+  readonly id: "hashtags.trending";
+  readonly category: "hashtags";
+}>, Readonly<{
+  readonly id: "hashtags.posts";
+  readonly category: "hashtags";
+}>, Readonly<{
+  readonly id: "search.all";
+  readonly category: "search";
+}>, Readonly<{
+  readonly id: "files.get";
+  readonly category: "files";
+}>, Readonly<{
+  readonly id: "subscription.status";
+  readonly category: "subscription";
+}>, Readonly<{
+  readonly id: "subscription.methods";
+  readonly category: "subscription";
+}>, Readonly<{
+  readonly id: "verification.status";
+  readonly category: "verification";
+}>, Readonly<{
+  readonly id: "platform.changelog";
+  readonly category: "platform";
+}>, Readonly<{
+  readonly id: "platform.announcements";
+  readonly category: "platform";
+}>, Readonly<{
+  readonly id: "platform.portal";
+  readonly category: "platform";
+}>, Readonly<{
+  readonly id: "status.get";
+  readonly category: "platform";
+}>];
+/** Имя операции, доступное в `cache({ operations: … })`. */
+type CacheOperationId = (typeof CACHE_OPERATIONS)[number]['id'];
+/** Раздел операции. */
+type CacheOperationCategory = (typeof CACHE_OPERATIONS)[number]['category'];
+/** Проверяет публичное имя кэшируемой операции. */
+declare function isCacheOperationId(value: string): value is CacheOperationId;
+/** Находит читающую операцию по стабильному семантическому ID. */
+declare function cacheOperation(operationId: OperationId): (typeof CACHE_OPERATIONS)[number] | undefined;
+//#endregion
+//#region src/index.d.ts
 declare module 'itd-api' {
-    interface RequestOptions {
-        /** Управление кэшем подключённого `@itd-api/cache`. */
-        cache?: CacheMode | undefined;
-    }
+  interface OperationAnnotations {
+    /** Правило кэширования операции подключаемого модуля. */
+    readonly cache?: {
+      readonly kind: typeof CachePolicyKind.Query;
+      readonly scope?: CachePolicyScope | undefined;
+    } | {
+      readonly kind: typeof CachePolicyKind.Mutation;
+      readonly invalidates: readonly OperationId[] | CacheInvalidation;
+      readonly scope?: typeof CachePolicyScope.Account | undefined;
+    } | undefined;
+  }
+  interface RequestExtensions {
+    /** Управление кэшем подключённого `@itd-api/cache`. */
+    cache?: CacheMode | undefined;
+  }
 }
-
-export { CACHE_ROUTES, CacheError, type CacheMode, CacheModes, type CacheOptions, type CachePlugin, type CacheRoute, type CacheRouteCategory, type CacheRouteId, buildCacheKey, cache, cacheRoute, isCacheRouteId };
+//#endregion
+export { CACHE_OPERATIONS, CacheError, CacheInvalidation, type CacheMode, CacheModes, type CacheOperation, type CacheOperationCategory, type CacheOperationId, type CacheOptions, type CachePlugin, CachePolicyKind, CachePolicyScope, buildCacheKey, cache, cacheOperation, isCacheOperationId };
+//# sourceMappingURL=index.d.ts.map