Browser Cache with TTL

A tiny, dependency-free browser cache with TTL support, automatic expiration, and smart fallback.

• Uses localStorage when available
• Falls back to in-memory Map (Incognito / restricted environments)
• Written in TypeScript
• Automatic cleanup by TTL (not lazy-only)
• Simple and predictable API

Installation

npm install browser-cache-ttl

or

yarn add browser-cache-ttl

import { CacheManager } from 'browser-cache-ttl';

const cache = new CacheManager();

cache.set('token', 'abc123', 60); // 1 minute

const token = cache.get<string>('token');
// -> 'abc123' or null if expired

TTL (Time To Live)

Each entry must define a TTL in seconds.

cache.set('user', { id: 1, name: 'Alice' }, 30);

After expiration, the value is automatically removed.

Automatic Cleanup

The cache runs a background cleanup task that removes expired entries.

Default cleanup interval: 60 seconds

You can customize it:

const cache = new CacheManager({
  cleanupIntervalMs: 30 // every 30 seconds
});

You can also stop cleanup if needed:

cache.destroy();

Type Safety

The cache is fully typed.

cache.set('settings', { theme: 'dark' }, 10);

const settings = cache.get<{ theme: string }>('settings');

API

set<T>(key: string, value: T, ttlMs: number): void

Stores a value with TTL.

get<T>(key: string): T | null

Returns the value if it exists and is not expired.

has(key: string): boolean

Checks if a key exists and is not expired.

delete(key: string): void

Removes a key from cache.

stopCleanupTask(): void

Stops automatic TTL cleanup.

Storage Strategy

| Environment | Storage Used | | ---------------------- | --------------- | | Normal browser mode | localStorage | | Incognito / restricted | In-memory Map |

Example: Cache with Fallback

const cache = new CacheManager();

cache.set('session', 'active', 5);

setTimeout(() => {
  console.log(cache.get('session')); // null after expiration
}, 6000);

Browser Support

• Chrome
• Firefox
• Safari
• Edge Works in Incognito / Private mode.

License

MIT

Free to use. Free to modify. Free for everyone.