Evented LRU TTL cache for Node.js and browsers
- A cache with a configurable number of expiring entries.
- Reading an expired entry removes it from the cache.
- When the cache is full, Least-Recently-Used entries are evicted first.
npm install @brokerloop/ttlcache --save
import { TTLCache } from '@brokerloop/ttlcache';
const cache = new TTLCache<string, number>({
ttl: 5000,
max: 10,
clock: Date
});
cache.set('a', 123);
cache.has('a'); // true
cache.get('a'); // 123
cache.get('b'); // undefined
cache.delete('a'); // 123
cache.empty.on(() => {
// cache is empty
});
cache.full.on(() => {
// cache is full
});
cache.evict.on(({ key, val }) => {
// entry evicted
});
{
ttl: 1000, // default entry TTL in ms
max: Infinity, // max number of entries in cache
clock: Date as Clock // cache-relative clock
}
By default, the cache uses Date.now()
to expire entries. This works while the system date/time do not change. You can provide your own implementation of the Clock
interface:
interface Clock {
now: () => number; // must be monotonically increasing
[_: string]: any;
}
const clock = (() => {
let time = 0;
const clock: Clock = {
now: () => time,
pass: (ms: number) => time += ms
};
return clock;
})();
Returns the size of the cache, including expired entries. Run cleanup()
first to obtain valid cache size.
Returns an iterator over valid cache entry keys, from newest to oldest. Expired entries are not evicted.
Returns an iterator over valid cache entry values, from newest to oldest. Expired entries are not evicted.
Returns an iterator over valid cache entries, from newest to oldest. Expired entries are not evicted.
Checks if key
exists in the cache. Does not evict the entry if expired.
Finds an entry by the given key
. Returns undefined
if not found or if the entry is expired, also evicting it.
Creates an entry at key
, evicting the cache's LRU entry if the cache is full. If an expired entry already exists at key
, its LRU-age is refreshed but it is not evicted.
Finds and removes an entry at key
. Returns the entry value if it was removed, or undefined
otherwise.
Evicts all expired entries from the cache. Pass emit: false
to not emit evict
events.
Resizes the cache to the given max
size. When growing, no entries are evicted. When shrinking, entries are evicted as needed, by oldest LRU-age, until the new max
is reached. Pass emit: false
to not emit evict
events.
Empties the cache, removing all entries, without firing signals.
Events (via Signal)
Signal fired after cache becomes empty. Does not fire on clear()
.
Signal fired after cache becomes full.
Signal fired after a cache entry is evicted. The evicted entry { key: K, val: V }
is passed as an argument. Does not fire on delete()
and clear()
.