synapse-storage/dist/api/components/query-storage.d.ts

Набор инструментов для управления состоянием и апи-запросами

import { IStorage, StorageKeyType } from '../../core';
import { CacheConfig, CreateApiClientOptions, StorageOption } from '../types/api.interface';
import { EndpointConfig } from '../types/endpoint.interface';
import { QueryOptions, Unsubscribe } from '../types/query.interface';
/**
 * Менеджер хранилища для API
 * Объединяет в себе функционал хранилища и управления кэшем
 */
export declare class QueryStorage {
    private readonly storageExternal;
    private readonly globalCacheConfig;
    /** Экземпляр хранилища */
    private storage;
    private cleanupInterval;
    /** Индекс тегов: tag → Set<cacheKey> для быстрой инвалидации */
    private tagIndex;
    /** Подписчики на событие инвалидации кэша (шина для авто-рефетча хуков) */
    private invalidateListeners;
    /** Настройки кэша по умолчанию */
    private defaultCacheOptions;
    /** Флаг завершённой инициализации */
    private _initialized;
    /** Промис текущей инициализации */
    private _initPromise;
    constructor(storageExternal: StorageOption, globalCacheConfig: CreateApiClientOptions['cache']);
    initialize(): Promise<this>;
    private _doInitialize;
    private createStorage;
    private startCleanupInterval;
    /**
     * Получает экземпляр хранилища
     */
    getStorage(): IStorage | null;
    /**
     * Является ли текущее хранилище синхронным (Memory/LocalStorage).
     * Только для таких хранилищ доступно синхронное чтение кэша ({@link getCachedResultSync}).
     */
    isSyncStorage(): boolean;
    /**
     * Подписка на событие инвалидации кэша. Колбэк получает список тегов, которые
     * были инвалидированы (через мутацию с `invalidatesTags` или ручную инвалидацию).
     * Используется хуками для авто-рефетча активных запросов после мутаций.
     */
    onCacheInvalidate(listener: (tags: string[]) => void): Unsubscribe;
    /** Уведомляет подписчиков шины об инвалидации указанных тегов */
    private emitCacheInvalidate;
    /**
     * Синхронное чтение результата из кэша (fast-path для SSR-гидрации).
     * Работает только на синхронных хранилищах (Memory/LocalStorage) — читает из
     * снапшота `getStateSync()` без async-тика, поэтому данные доступны уже на
     * первом рендере и не возникает «вспышки» loading. Для async-хранилищ
     * (IndexedDB) и протухших записей возвращает `undefined`.
     *
     * В отличие от {@link getCachedResult}, НЕ мутирует метаданные и не удаляет
     * протухшие записи (чистое чтение, безопасно вызывать во время рендера).
     */
    getCachedResultSync<T>(cacheKey: StorageKeyType): T | undefined;
    /**
     * Создает ключ кэша для запроса с учетом заголовков
     * @param endpoint Имя эндпоинта
     * @param params Параметры запроса (все что посчитаем нужным)
     */
    createCacheKey<CacheParams extends Record<string, any>>(endpoint: string, params: CacheParams): [StorageKeyType, Record<string, any> | undefined];
    /**
     * Получает результат запроса из кэша
     */
    getCachedResult<T>(cacheKey: StorageKeyType): Promise<T | undefined>;
    /**
     * Сохраняет результат запроса в кэш
     * @param cacheKey Ключ кэша
     * @param data Данные для кэширования
     * @param cacheOptions Метаданные
     * @param cacheParams Параметры которые влияли на создание ключа
     * @param tags Тэги эндпоинта
     */
    setCachedResult<T, CacheParams extends Record<string, any>>(cacheKey: StorageKeyType, data: T, cacheOptions: Exclude<CacheConfig, boolean>, cacheParams: CacheParams, tags: string[]): Promise<void>;
    /**
     * Проверяет, должен ли запрос быть кэширован
     * @param endpointConfig Конфигурация эндпоинта
     * @param options Опции запроса
     * @param method HTTP-метод запроса (только GET кэшируется по REST-стандарту)
     * @returns true если запрос должен кэшироваться
     */
    shouldCache(endpointConfig?: EndpointConfig, options?: QueryOptions, method?: string): boolean;
    /**
     * Создает итоговую конфигурацию кэширования для конкретного эндпоинта
     * Объединяет глобальный конфиг с текущим
     * @param endpointConfig Конфигурация эндпоинта
     */
    createCacheConfig(endpointConfig?: EndpointConfig): {
        ttl?: number;
        cleanup?: {
            enabled: boolean;
            interval?: number;
        };
        invalidateOnError?: boolean;
    };
    /**
     * Инвалидирует кэш по тегам (использует индекс для O(1) поиска по тегу)
     * @param tags Теги для инвалидации
     */
    invalidateCacheByTags(tags: string[]): Promise<void>;
    /**
     * Инвалидирует кэш по ключу
     * @param cacheKey Ключ кэша
     */
    invalidateCache(cacheKey: StorageKeyType): Promise<void>;
    /**
     * Выполняет очистку всех просроченных записей кэша
     */
    cleanup(): Promise<void>;
    /**
     * Уничтожает хранилище и освобождает ресурсы
     */
    destroy(): Promise<void>;
    /**
     * Гидрация кэша снапшотом (SSR/server-state). Заменяет состояние хранилища и
     * перестраивает индекс тегов, чтобы инвалидация по тегам работала сразу после
     * переноса с сервера. Абсолютные `expiresAt` в метаданных переживают перенос,
     * поэтому TTL продолжает считаться корректно.
     */
    hydrate(state: Record<string, any>): Promise<void>;
    /**
     * Перестраивает индекс тегов из существующих записей в storage
     * Вызывается при инициализации для восстановления после перезагрузки
     */
    private rebuildTagIndex;
    /**
     * Удаляет ключ из индекса тегов
     */
    private removeKeyFromTagIndex;
}