Time Cache

Легковесный кэш с временем жизни записей (TTL) для браузерных приложений. Использует localStorage и автоматически удаляет просроченные данные.

Особенности

• ⏱ Автоматическое удаление просроченных записей
• 🛡️ Самовосстановление при переполнении хранилища
• 🔑 Поддержка префиксов ключей для изоляции данных (по умолчанию 'timecache_')
• TTL по умолчанию 10 минут
• Максимальный TTL 30 дней (при попытке установить больше - будет обрезано)
• 🧩 Паттерн Singleton (единственный экземпляр)
• 🧪 100% покрытие тестами

Установка

npm install time-cache-ttl
# или
yarn add time-cache-ttl

Использование

import TimeCache from 'time-cache-ttl';

// Инициализация кэша
const cache = TimeCache.getInstance();

// Сохранение значения на 10 минут (по умолчанию)
cache.set('user', { id: 42, name: 'John' });

// Сохранение значения на 5 секунд (с явным указанием TTL)
cache.set('session', { token: 'abc123' }, 5000);

// Получение значения
const user = cache.get('user');
console.log(user); // { id: 42, name: 'John' }

// Удаление значения
cache.delete('user');

// Установка префикса для ключей (по умолчанию 'timecache_')
TimeCache.setPrefix('app_v1_');

// Установка своего TTL по умолчанию (1 час)
TimeCache.setDefaultTTL(3_600_000);

Расширенное использование

Обработка переполнения хранилища

try {
  cache.set('large-data', bigData, 60000);
} catch (e) {
  console.error('Storage error:', e.message);
  // Автоматически очищает просроченные данные и повторяет попытку
}

Автоматическая очистка при инициализации

// При создании экземпляра автоматически удаляются:
// - Просроченные записи
// - Поврежденные данные
// - Записи без префикса (если установлен) или с несоответствующим префиксом
const cache = new TimeCache();  // или TimeCache.getInstance()

API

TimeCache.getInstance(storage?)

Возвращает экземпляр кэша (по умолчанию использует localStorage)

TimeCache.setPrefix(prefix)

Устанавливает префикс для всех ключей. По умолчанию используется префикс 'timecache_'. При изменении префикса после инициализации старые записи не будут автоматически очищены.

TimeCache.setDefaultTTL(ttl)

Устанавливает время жизни записей по умолчанию (в миллисекундах). По умолчанию: 600_000 (10 минут).

cache.set(key, value, ttl)

Сохраняет значение:

• key - ключ записи
• value - данные (должны быть JSON-сериализуемы)
• ttl - время жизни в миллисекундах (максимум 30 дней)

cache.get(key)

Возвращает значение или null если:

• Запись отсутствует
• Запись просрочена
• Данные повреждены

cache.delete(key)

Удаляет запись по ключу

cache.cleanup()

Вручную запускает очистку просроченных записей

Разработка

Установка зависимостей

npm install

Запуск тестов

npm test

Проверка покрытия

npm run test:coverage

Лицензия

Этот проект распространяется под лицензией MIT.