cachemate
v1.0.0
Published
A simple in-memory cache with TTL and eviction
Downloads
8
Maintainers
Readme
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 newCacheMate
instance with a specified maximum size for the cache. Default is 100.async get(key)
: Retrieves the value associated withkey
. Returnsnull
if the key does not exist or has expired.async set(key, value, ttl)
: Sets the value forkey
with a specified TTL (time-to-live) in milliseconds.evict(key)
: Manually evicts the specifiedkey
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.