Cache Types Documentation

This package provides interfaces for creating various types of cache objects with different eviction policies. It includes pre-configured options such as FIFO (First-In, First-Out), LIFO (Last-In, First-Out), RR (Random Eviction), MRU (Most Recently Used), and LRU (Least Recently Used) cache interfaces, along with a customizable option that allows you to define other eviction policies.

Installation

1npm install cache-types

Usage

Here's an example of how to use the package to create a custom cache type with a specific eviction policy:

1const { CacheConstructor } = require('cache-types');
2
3// Create a custom cache type that evicts the first two keys added
4const DoubleEvictionCache = CacheConstructor(
5    (storageMap, self) => {
6        self.del(self.firstKey); // Remove the first key
7        self.del(self.firstKey); // Remove the second key
8    },
9    { relocationOnGet: true } // When keys are attained with 'get', relocate them as the last ones to evict
10);
11
12// Create a new custom cache instance
13const cache = new DoubleEvictionCache(100, { ttl: 1000 });
14
15cache.set(9, 1000);
16console.log(cache.get(9)); // Outputs: 1000

API Documentation

---

CacheConstructor(_evictionPolicy = () => {}, { relocationOnGet = false })

Creates a new custom cache type based on the provided eviction policy and relocation settings.

Parameters:

• _evictionPolicy: A function that defines the eviction logic. It receives two parameters:
  • storageMap: The internal storage map of the cache as a Map.
  • self: Represents the keyword this inside the class.
• relocationOnGet: A boolean value that determines whether to relocate keys upon retrieval (true) or not (false). This is useful for time-aware policies but may not be ideal for position-aware policies like FIFO.

Returns:

A new ES6 class extending NoPolicyCache, with the new name.

Example Usage of CacheConstructor

1const CustomCache = CacheConstructor(
2    (storageMap, self) => {
3        // Eviction logic here
4        const keys = [...storageMap.keys()];
5        if (keys.length > 0) {
6            self.del(keys[0]); // Remove the first key
7        }
8        if (keys.length > 1) {
9            self.del(keys[1]); // Remove the second key
10        }
11    },
12    { relocationOnGet: true }
13);

---

Cache Class (Cache)

The Cache class is a base class that provides the core functionality for cache storage and eviction. It includes methods to set, get, delete keys, and more.

Pre-configured cache types:

• LRUCache: A least recently used (LRU) cache that evicts items based on their last access time.
• MRUCache : A most recently used (MFU) cache that evicts items based on their frequency of access.
• FIFOCache: A first-in, first-out (FIFO) cache that evicts items based on their order of insertion.
• LIFOCache: A last-in, first-out (LIFO) cache that evicts items based on their order of insertion.
• RandomCache: A random cache that evicts a random item

Shared Methods for the Cache class and all pre-configured cache types:

• constructor(capacity, ttl, { relocationOnGet = true }): Initializes the cache with a given capacity and optional time-to-live (TTL).
  • Parameters:
    • capacity: The maximum number of items the cache can hold.
    • ttl: The time-to-live for cached items in milliseconds.
    • relocationOnGet: Determines whether to relocate keys upon retrieval (true) or not (false).
• get size: Returns the current number of items in the cache.
• get capacity: Returns the maximum capacity of the cache.
• get keys: Returns an array of all keys currently in the cache.
• get values: Returns an array of all values currently in the cache.
• get first: Returns the value of the oldest item in the cache.
• get last: Returns the value of the most recently added item in the cache.
• get firstKey: Returns the key of the oldest item in the cache.
• get lastKey: Returns the key of the most recently added item in the cache.
• get lastHit: Returns the key of the most recently accessed item.
• get stats: Returns the statistics object tracking hits, misses, expired items, and evicted items.
• evictionPolicy(storageInstance): Defines the eviction logic for the cache. This method should be overridden by subclasses to implement specific eviction policies.
• evict(): Evicts an item based on the configured eviction policy.
• flushStats(): Resets the statistics object.
• flush(): Clears all items from the cache.
• has(key): Checks if a key exists in the cache.
• peek(key): Returns the value of a key without updating hit stats.
• del(key): Removes and returns the value of a key.
• get(key): Retrieves a key's value, updates hit stats, and relocates keys if relocationOnGet is set to true.
• set(key, value, ttl): Adds or updates a key with an optional TTL.
• getInfo(key): Returns information about the cached item including its timestamp and remaining TTL.
• resize(size): Changes the cache capacity and evicts extra items if necessary.

---

Usage Examples: (MRUCache | RRCache | FIFOCache | LIFOCache | LRUCache)

The Most Recently Used (MRU) cache removes the most recently used item first. When a new item is added and the cache is full, the most recently used item is removed.

Class Usage:

1const { MRUCache } = require('cache-types');
2
3// Create an instance of MRUCache with a capacity of 3
4const mruCache = new MRUCache(3);
5
6mruCache.set('key1', 'value1');
7mruCache.set('key2', 'value2');
8mruCache.set('key3', 'value3');
9console.log(mruCache.get('key3')); // Outputs: value3
10// Adding a new item will evict the most recently used one (key3)
11mruCache.set('key4', 'value4');
12console.log(mruCache.get('key3')); // Outputs: undefined, the value was evicted