Package Exports

@hyperttp/cache
@hyperttp/cache/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@hyperttp/cache) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

hyperttp-cache

English | Русский

🌐 Language

🇺🇸 English
🇷🇺 Русский

Сверхбыстрый, изоморфный плагин кэширования и дедупликации параллельных запросов для высокопроизводительного HTTP-клиента Hyperttp. Оптимизирован для рантаймов Bun и Node.js.

Плагин бесшовно встраивается в плоский конвейер жизненного цикла HyperCore, защищая сервер от лавинообразной нагрузки (Cache Stampede Protection) и предоставляя умное in-memory хранилище на базе стратегии LRU (Least Recently Used).

🔥 Ключевые фичи

🧠 LRU-стратегия с поддержкой TTL: Автоматическое вытеснение старых записей при достижении лимита. При каждом GET-запросе возраст записи сбрасывается (updateAgeOnGet: true), удерживая горячие данные в памяти.
🚀 In-Flight Deduplication: Веерные параллельные запросы на один и тот же URL группируются в один сетевой hot path. Ответ клонируется и раздается всем подписчикам одновременно.
🔄 HTTP Revalidation: Полная поддержка проверок свежести по ETag (If-None-Match) и Last-Modified (If-Modified-Since). Автоматически гидрирует пустые 304 ответы актуальным телом из памяти.
🛡️ Безопасность при сбоях: При возникновении сетевых ошибок пул ожидания мгновенно разрывается (onError), разблокируя повторные попытки запросов.
📊 Расширение Ядра: Автоматически инжектирует методы управления кэшем (clearCache) и добавляет метрику cacheSize в системную статистику getStats().

📦 Установка

bun add hyperttp-cache
# или
npm install hyperttp-cache

🚀 Быстрый старт

Просто импортируйте фабрику withCache и передайте её в массив плагинов вашего клиента. Настройки кэша передаются в глобальный конфиг.

import { createClient } from "@hyperttp/core";
import { withCache } from "hyperttp-cache";

const client = createClient({
  plugins: [withCache()],
  cache: {
    enabled: true,
    ttl: 60_000, // 1 минута (по умолчанию 300_000 мс)
    maxSize: 1000, // Лимит в 1000 элементов (по умолчанию 500)
    methods: ["GET"], // HTTP-методы, разрешенные для кэширования
  },
});

// 1. Первый запрос уходит в сеть и наполняет кэш
const res1 = await client.get("/api/data");

// 2. Второй последующий запрос вернет изолированный клон из кэша
const res2 = await client.get("/api/data");

⚙️ Параметры конфигурации (`CacheManagerOptions`)

Конфигурация плагина полностью типизирована и расширяет интерфейс настроек клиента:

Параметр	Тип	По умолчанию	Описание
`cache.enabled`	`boolean`	`false`	Флаг активации/деактивации слоя кэширования.
`cache.ttl`	`number`	`300_000` (5 мин)	Время жизни записи в кэше (в миллисекундах).
`cache.maxSize`	`number`	`500`	Максимальное количество записей в LRU-кэше до начала вытеснения.
`cache.methods`	`Method[]`	`["GET"]`	Массив HTTP-методов, для которых разрешено кэширование ответов.

🛠️ API Расширения Ядра

Плагин расширяет глобальные интерфейсы декларации типов @hyperttp/types. Вам становятся доступны следующие методы прямо из инстанса ядра:

Очистка кэша

// Очистить кэш полностью
client.clearCache();

// Удалить конкретный URL из кэша
client.clearCache("/api/data");

Телеметрия

Если ваше ядро поддерживает метод getStats(), плагин автоматически подмешает туда текущий размер кэша:

const stats = client.getStats();
console.log(stats.cacheSize); // Выведет текущее количество записей в LRU-хранилище

📐 Архитектура жизненного цикла

Плагин использует атомарные независимые хуки вместо тяжелых middleware-оберток:

onRequest: Проверяет наличие точного совпадения в CacheManager. Если запись свежая и не требует проверки сервера — возвращает её клон, завершая цепочку. Если идет активный запрос к этому же URL — подписывается на его Promise. Если запись требует валидации, подмешает заголовки If-None-Match / If-Modified-Since.
onResponse: Перехватывает успешные ответы. Превращает пустой 304 Not Modified обратно в полноценный 200 OK, восстанавливая данные из локальной памяти. Записывает новые 200 ответы с валидными ETag. Разрешает (resolves) ожидания всех In-Flight подписчиков.
onError: В случае сетевого сбоя вычищает карту активных задач, чтобы не заблокировать последующие повторные вызовы к упавшему эндпоинту.

📄 Лицензия

MIT

@hyperttp/cache