CacheMate

CacheMate is a simple in-memory cache implementation for Node.js with support for TTL (Time-to-Live) expiration and automatic eviction of the oldest entries when the cache exceeds its maximum size. It also provides cache statistics.

Features

• TTL Expiration: Automatically expires cache entries based on a specified TTL.
• Eviction: Evicts the oldest entries when the cache size exceeds the maximum limit.
• Statistics: Provides hit, miss, eviction, and set counts for monitoring cache usage.
• Automatic Eviction Process: Periodically checks for and removes expired cache entries.

Installation

Install the package via npm:

npm install cachemate

Usage

Basic Example

const CacheMate = require('cachemate');

// Create a new cache with a maximum size of 2
const cache = new CacheMate(2);

// Set cache entries with TTL of 100ms
cache.set('key1', 'value1', 100);
cache.set('key2', 'value2', 100);

// Retrieve cache entries
cache.get('key1').then(value => console.log(value)); // Outputs: 'value1'

// Wait for TTL to expire and retrieve entries again
setTimeout(() => {
    cache.get('key1').then(value => console.log(value)); // Outputs: null (expired)
    cache.get('key2').then(value => console.log(value)); // Outputs: null (expired)
}, 150);

Handling Eviction

const CacheMate = require('cachemate');

// Create a new cache with a maximum size of 2
const cache = new CacheMate(2);

// Set cache entries
cache.set('key1', 'value1', 100);
cache.set('key2', 'value2', 100);

// Add a third entry to trigger eviction of the oldest entry ('key1')
cache.set('key3', 'value3', 100);

// Retrieve cache entries
cache.get('key1').then(value => console.log(value)); // Outputs: null (evicted)
cache.get('key2').then(value => console.log(value)); // Outputs: 'value2'
cache.get('key3').then(value => console.log(value)); // Outputs: 'value3'

Clearing the Cache

const CacheMate = require('cachemate');

// Create a new cache with a maximum size of 2
const cache = new CacheMate(2);

// Set cache entries
cache.set('key1', 'value1', 100);
cache.set('key2', 'value2', 100);

// Clear the cache
cache.clear();

// Retrieve cache entries after clearing
cache.get('key1').then(value => console.log(value)); // Outputs: null (cleared)
cache.get('key2').then(value => console.log(value)); // Outputs: null (cleared)

// Check cache statistics
const stats = cache.getStats();
console.log(stats); // Outputs: { hits: 0, misses: 2, evictions: 0, sets: 0 }

Cache Statistics

const CacheMate = require('cachemate');

// Create a new cache with a maximum size of 2
const cache = new CacheMate(2);

// Set cache entries
cache.set('key1', 'value1', 100);
cache.set('key2', 'value2', 100);

// Retrieve some cache entries
cache.get('key1');
cache.get('key2');

// Check cache statistics
const stats = cache.getStats();
console.log(stats);
// Example Output: { hits: 2, misses: 0, evictions: 0, sets: 2 }

Methods

• constructor(maxSize): Creates a new CacheMate instance with a specified maximum size for the cache. Default is 100.
• async get(key): Retrieves the value associated with key. Returns null if the key does not exist or has expired.
• async set(key, value, ttl): Sets the value for key with a specified TTL (time-to-live) in milliseconds.
• evict(key): Manually evicts the specified key from the cache.
• clear(): Clears all cache entries and resets statistics.
• getStats(): Returns an object containing cache statistics (hits, misses, evictions, sets).
• log(message): Logs a message to the console (useful for debugging).

Notes

• The cache performs automatic eviction of expired entries every second.
• The eviction process is restarted whenever the cache is cleared.