fixed-cache

A fixed-capacity, in-memory cache for JavaScript with pluggable eviction strategies.

Features

• Fixed capacity — initialize with a maximum number of items
• Pluggable eviction — swap strategies at initialization or runtime
• Three built-in strategies: LRU, MRU, LFU (heap-based)
• Zero runtime dependencies

Installation

npm install fixed-cache

Usage

import { Cache, LRUStrategy, MRUStrategy, LFUStrategy } from 'fixed-cache';

const cache = new Cache({ capacity: 100, strategy: new LRUStrategy() });

cache.set('user:1', { name: 'Alice' });
cache.get('user:1'); // { name: 'Alice' }

// Swap strategy at runtime
cache.strategy = new LFUStrategy();

Design Decisions

Strategy Pattern

Eviction logic is decoupled from the cache itself. Each strategy implements three methods:

| Method | Purpose | |----------------|----------------------------------------------| | onInsert(key) | Called when a new key is added | | onAccess(key) | Called when an existing key is read or updated | | evict() | Returns the key to remove |

This makes it trivial to add new strategies — just implement the interface.

LRU / MRU — Map Iteration Order

Both leverage the fact that JavaScript Map preserves insertion order. Accessing a key deletes and re-inserts it, moving it to the end. LRU evicts from the front; MRU evicts from the back.

LFU — Heap-Based

The LFU strategy maintains per-key frequency counts and stores them in a MinHeap. This ensures evict() always extracts the least-frequently-used key in O(log n) time. The heap supports in-place priority updates when a key's frequency changes.

Runtime Strategy Swap

Assigning cache.strategy = new SomeStrategy() re-registers all existing keys with the new strategy via onInsert, so the new strategy starts with a clean view of the cache contents.

Running Tests

npm test

Tests use Vitest (dev dependency only) and cover:

• Basic get/set behavior
• Eviction for each strategy (LRU, MRU, LFU)
• Edge cases: capacity = 1, key overwrites, missing keys
• Runtime strategy swapping