Least-Recently-Used and First-In-First-Out caches for Client or Server.
Getting started
import { Lru, Fifo } from 'toad-cache'const lruCache = new Lru(max, ttl = 0)const fifoCache = new Fifo(max, ttl = 0)
clear
Method
Clears the contents of the cache
Example
cache.clear()
delete
Method
Removes item from cache
param {String} key Item key
Example
cache.delete('myKey')
deleteMany
Method
Removes items from cache
param {String[]} keys Item keys
Example
cache.deleteMany(['myKey', 'myKey2'])
evict
Method
Evicts the least recently used item from cache
Example
cache.evict()
expiresAt
Method
Gets expiration time for cached item
param {String} key Item keyreturn {Mixed} Undefined or number (epoch time)
Example
const item = cache.expiresAt('myKey')
first
Property
Item in "first" or "bottom" position
Example
const cache = new Lru()cache.first // null - it's a new cache!
get
Method
Gets cached item and marks it as recently used (pushes to the back of the list of the candidates for the eviction)
param {String} key Item keyreturn {Mixed} Undefined or Item value
Example
const item = cache.get('myKey')
getMany
Method
Gets multiple cached items and marks them as recently used (pushes to the back of the list of the candidates for the eviction)
param {String[]} keys Item keysreturn {Mixed[]} Undefined or Item values
Example
const item = cache.getMany(['myKey', 'myKey2'])
keys
Method
Returns an Array of cache item keys.
return {Array} Array of keys
Example
console.log(cache.keys())
max
Property
Max items to hold in cache (1000)
Example
const cache = new Lru(500)cache.max // 500
last
Property
Item in "last" or "top" position
Example
const cache = new Lru()cache.last // null - it's a new cache!
set
Method
Sets item in cache as first
param {String} key Item keyparam {Mixed} value Item value
Example
cache.set('myKey', { prop: true })
size
Property
Number of items in cache
Example
const cache = new Lru()cache.size // 0 - it's a new cache!
ttl
Property
Milliseconds an item will remain in cache; lazy expiration upon next get() of an item
Example
const cache = new Lru()cache.ttl = 3e4
Hit/miss/expiration tracking
In case you want to gather information on cache hit/miss/expiration ratio, as well as cache size and eviction statistics, you can use LruHitStatistics class:
const sharedRecord = new HitStatisticsRecord() // if you want to use single record object for all of caches, create it manually and pass to each cacheconst cache = new LruHitStatistics({ cacheId: 'some-cache-id', globalStatisticsRecord: sharedRecord, statisticTtlInHours: 24, // how often to reset statistics. On every rotation previously accumulated data is removed max: 1000, ttlInMsecs: 0,})
You can retrieve accumulated statistics from the cache, or from the record directly:
// this is the sameconst statistics = sharedRecord.getStatistics()const alsoStatistics = cache.getStatistics()/*{ 'some-cache-id': { '2023-04-06': { cacheSize: 100, // how many elements does cache currently have evictions: 5, // how many elements were evicted due to cache being at max capacity expirations: 0, // how many elements were removed during get due to their ttl being exceeded hits: 0, // how many times element was successfully retrieved from cache during get emptyHits: 0, // out of all hits, how many were null, undefined or ''? falsyHits: 0, // out of all hits, how many were falsy? misses: 1, // how many times element was not in cache or expired during get invalidateOne: 1, // how many times element was invalidated individually invalidateAll: 2, // how many times entire cache was invalidated sets: 0, // how many times new element was added }, },}Note that date here reflects start of the rotation. If statistics weren't rotated yet, and another day started, it will still be counted against the day of the rotation start*/