Toad Cache
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 key
return {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 key
return {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 keys
return {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 key
param {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 cache
const 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 same
const 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
*/
License
Copyright (c) 2023 Igor Savin
Based on tiny-lru, created by Jason Mulligan
Licensed under the MIT license.
