exbotanical/tenure

Manageable LRU in-memory cache instance for fast lookups and configurable eviction policies

Tenure | Manageable LRU caching

Tenure is a manageable LRU cache instance that uses hashmap lookups and an Open Doubly Linked List to enact the Least-Recently Used algorithm

Algorithm

Installation

npm install tenure

OR

yarn add tenure

Supported Environments

Tenure currently supports UMD, CommonJS (node versions >= 10), and ESM build-targets

API Reference

LruCache

• LruCache
  • new LruCache(capacity, cb)
  • .get(key) ⇒ any | null
  • .put(key, value) ⇒ boolean
  • .del(key) ⇒ boolean
  • .keys() ⇒ array
  • .has(key) ⇒
  • .lru() ⇒ array | null
  • .drop()
  • .resize(cap) ⇒ number
  • .size() ⇒ number
  • .capacity() ⇒ number

new LruCache(capacity, cb)

Implements a canonical Least Recently-Used Cache

Param	Type	Description
capacity	number	The maximum capacity (items) of the cache; beyond this threshold, the eviction policy is enacted. Defaults to 10
cb	function	Optional callback to be invoked upon each eviction; called with evicted item key, value

lruCache.get(key) ⇒ any | null

Retrieve an item from the cache; if extant, the item will be designated 'most-recently used' Returns: any | null - The retrieved value, if extant; else, null

Param	Type
key	any

lruCache.put(key, value) ⇒ boolean

Add or update a given key / value pair in the cache

Put transactions will move the key to the head of the cache, designating it as 'most recently-used'

If the cache has reached the specified capacity, Put transactions will also enact the eviction policy, thereby removing the least recently-used item Returns: boolean - A boolean indicating whether an eviction occurred

Param	Type
key	any
value	any

lruCache.del(key) ⇒ boolean

Remove an item corresponding to a given key from the cache, if extant Returns: boolean - A boolean indicating whether of not the delete transaction occurred

Param	Type
key	any

lruCache.keys() ⇒ array

Returns: array - An array of all keys currently extant in the cache

lruCache.has(key) ⇒

Verify the existence of a key in the cache without enacting the eviction policy Returns: A boolean flag verifying the existence (or lack thereof) of a given key in the cache

Param	Type
key	any

lruCache.lru() ⇒ array | null

Returns: array | null - the least recently-used key / value pair, or null if not extant

lruCache.drop()

Drop all items from the cache, effectively purging it

lruCache.resize(cap) ⇒ number

Resizes the cache capacity.

Invoking this transaction will evict all least recently-used items to adjust the cache, where necessary Returns: number - the number of evictions enacted

Param	Type	Description
cap	number	new capacity

lruCache.size() ⇒ number

Returns: number - the current size of the cache

lruCache.capacity() ⇒ number

Returns: number - the current maximum buffer capacity of the cache