@brokerloop/ttlcache
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.
Installation
npm install @brokerloop/ttlcache --save
Usage (TypeScript)
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
});
Options
{
ttl: 1000, // default entry TTL in ms
max: Infinity, // max number of entries in cache
clock: Date as Clock // cache-relative clock
}
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;
})();
Properties
size
Returns the size of the cache, including expired entries. Run cleanup() first to obtain valid cache size.
Methods
keys(): Iterator<K>
Returns an iterator over valid cache entry keys, from newest to oldest. Expired entries are not evicted.
values(): Iterator<V>
Returns an iterator over valid cache entry values, from newest to oldest. Expired entries are not evicted.
entries(): Iterator<{ key: K, val: V }>
Returns an iterator over valid cache entries, from newest to oldest. Expired entries are not evicted.
has(key: K): boolean
Checks if key exists in the cache. Does not evict the entry if expired.
get(key: K): V|undefined
Finds an entry by the given key. Returns undefined if not found or if the entry is expired, also evicting it.
set(key: K, val: V): void
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.
delete(key: K): V|undefined
Finds and removes an entry at key. Returns the entry value if it was removed, or undefined otherwise.
cleanup(opts = { emit: true }): void
Evicts all expired entries from the cache. Pass emit: false to not emit evict events.
resize(max: number, opts = { emit: true }): void
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.
clear(): void
Empties the cache, removing all entries, without firing signals.
Events (via Signal)
empty
Signal fired after cache becomes empty. Does not fire on clear().
full
Signal fired after cache becomes full.
evict
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().