Toad Cache

Least-Recently-Used and First-In-First-Out caches for Client or Server.

Getting started

1import { Lru, Fifo } from 'toad-cache'
2const lruCache = new Lru(max, ttl = 0)
3const fifoCache = new Fifo(max, ttl = 0)

clear

Method

Clears the contents of the cache

Example

1cache.clear()

delete

Method

Removes item from cache

param  {String} key Item key

Example

1cache.delete('myKey')

deleteMany

Method

Removes items from cache

param  {String[]} keys Item keys

Example

1cache.deleteMany(['myKey', 'myKey2'])

evict

Method

Evicts the least recently used item from cache

Example

1cache.evict()

expiresAt

Method

Gets expiration time for cached item

param  {String} key Item key
return {Mixed}      Undefined or number (epoch time)

Example

1const item = cache.expiresAt('myKey')

first

Property

Item in "first" or "bottom" position

Example

1const cache = new Lru()
2
3cache.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

1const 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

1const item = cache.getMany(['myKey', 'myKey2'])

keys

Method

Returns an Array of cache item keys.

return {Array} Array of keys

Example

1console.log(cache.keys())

max

Property

Max items to hold in cache (1000)

Example

1const cache = new Lru(500)
2
3cache.max // 500

last

Property

Item in "last" or "top" position

Example

1const cache = new Lru()
2
3cache.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

1cache.set('myKey', { prop: true })

size

Property

Number of items in cache

Example

1const cache = new Lru()
2
3cache.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

1const cache = new Lru()
2
3cache.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:

1const sharedRecord = new HitStatisticsRecord() // if you want to use single record object for all of caches, create it manually and pass to each cache
2
3const cache = new LruHitStatistics({
4  cacheId: 'some-cache-id',
5  globalStatisticsRecord: sharedRecord,
6  statisticTtlInHours: 24, // how often to reset statistics. On every rotation previously accumulated data is removed
7  max: 1000,
8  ttlInMsecs: 0,
9})

You can retrieve accumulated statistics from the cache, or from the record directly:

1// this is the same
2const statistics = sharedRecord.getStatistics()
3const alsoStatistics = cache.getStatistics()
4
5/*
6{
7  'some-cache-id': {
8    '2023-04-06': {
9      cacheSize: 100, // how many elements does cache currently have
10      evictions: 5, // how many elements were evicted due to cache being at max capacity    
11      expirations: 0, // how many elements were removed during get due to their ttl being exceeded
12      hits: 0, // how many times element was successfully retrieved from cache during get
13      emptyHits: 0, // out of all hits, how many were null, undefined or ''?
14      falsyHits: 0, // out of all hits, how many were falsy?      
15      misses: 1, // how many times element was not in cache or expired during get
16      invalidateOne: 1, // how many times element was invalidated individually
17      invalidateAll: 2, // how many times entire cache was invalidated
18      sets: 0, // how many times new element was added      
19    },
20  },
21}
22
23Note 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
24*/

License

Copyright (c) 2023 Igor Savin

Based on tiny-lru, created by Jason Mulligan

Licensed under the MIT license.