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

npm 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:

const { CacheConstructor } = require('cache-types');

// Create a custom cache type that evicts the first two keys added
const DoubleEvictionCache = CacheConstructor(
    (storageMap, self) => {
        self.del(self.firstKey); // Remove the first key
        self.del(self.firstKey); // Remove the second key
    },
    { relocationOnGet: true } // When keys are attained with 'get', relocate them as the last ones to evict
);

// Create a new custom cache instance
const cache = new DoubleEvictionCache(100, { ttl: 1000 });

cache.set(9, 1000);
console.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

const CustomCache = CacheConstructor(
    (storageMap, self) => {
        // Eviction logic here
        const keys = [...storageMap.keys()];
        if (keys.length > 0) {
            self.del(keys[0]); // Remove the first key
        }
        if (keys.length > 1) {
            self.del(keys[1]); // Remove the second key
        }
    },
    { relocationOnGet: true }
);

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:

const { MRUCache } = require('cache-types');

// Create an instance of MRUCache with a capacity of 3
const mruCache = new MRUCache(3);

mruCache.set('key1', 'value1');
mruCache.set('key2', 'value2');
mruCache.set('key3', 'value3');
console.log(mruCache.get('key3')); // Outputs: value3
// Adding a new item will evict the most recently used one (key3)
mruCache.set('key4', 'value4');
console.log(mruCache.get('key3')); // Outputs: undefined, the value was evicted