Toad Cache: LRU and FIFO Caching

3.7.0 · active · verified Sun Apr 19

Toad Cache is a JavaScript/TypeScript library offering in-memory Least-Recently-Used (LRU) and First-In-First-Out (FIFO) caching strategies suitable for both client-side (browser) and server-side (Node.js) environments. The current stable version is 3.7.0. Releases appear to be ad-hoc, driven by feature additions and bug fixes rather than a strict schedule. A key differentiator since version 3.0.0 is the direct export of `Lru` and `Fifo` classes, allowing direct instantiation with `new` rather than a factory function, providing a more idiomatic class-based API. It also supports optional cache statistics tracking (hit/miss/expiration) via the `LruHitStatistics` class and offers both Map-based and Object-based internal implementations for performance tuning. It provides methods for setting, getting, deleting, and managing cache entries, along with properties for cache size and configuration.

Common errors

```
TypeError: Lru is not a function
```
cause Attempting to instantiate `Lru` as a function instead of a class, or importing incorrectly after version 3.0.0.

fix Use the `new` keyword to instantiate: `const cache = new Lru(max, ttl)`. Ensure you are using named imports for ESM: `import { Lru } from 'toad-cache'` or correctly accessing the class property for CJS: `const Lru = require('toad-cache').Lru`.
```
SyntaxError: Named export 'Lru' not found. The requested module 'toad-cache' does not provide an export named 'Lru'
```
cause Trying to import a non-existent named export, possibly due to a typo or misunderstanding of the package's exports.

fix Double-check the import statement. For Toad Cache, `Lru` and `Fifo` are named exports. If you're importing a specialized version like `LruHitStatistics`, ensure that's what you're referencing: `import { Lru, Fifo, LruHitStatistics } from 'toad-cache'`.

Warnings

breaking Version 3.0.0 introduced a breaking change by getting rid of the constructor wrapper. Cache instances are now created directly using the `new` keyword with exported class constructors (`Lru`, `Fifo`, `LruHitStatistics`), instead of relying on factory functions.
Fix: Update your instantiation code from `const cache = Lru(max, ttl)` to `const cache = new Lru(max, ttl)`. Ensure you are importing the classes as named exports: `import { Lru, Fifo } from 'toad-cache'`.
gotcha The `ttl` (Time To Live) property defines how long an item remains in cache, but expiration is 'lazy'. An item will only be removed upon its next `get()` attempt after the TTL has passed, or during an eviction if the cache reaches its `max` size.
Fix: Be aware that expired items might still reside in the cache until accessed or evicted. If strict real-time expiration is required, consider implementing a background cleanup or checking `expiresAt()` manually.
gotcha When using `LruHitStatistics`, ensure that `cacheId` is unique if you intend to track multiple caches with a single `HitStatisticsRecord` instance, as statistics are aggregated by this ID. Also, `statisticTtlInHours` defines how often statistics are reset, which might not align with cache item TTL.
Fix: Assign a distinct `cacheId` for each `LruHitStatistics` instance sharing a `globalStatisticsRecord`. Understand that `statisticTtlInHours` dictates the rotation of aggregated usage data, not the expiration of individual cache items.

Install

npm install toad-cache npm
yarn add toad-cache yarn
pnpm add toad-cache pnpm

Imports

Lru
wrong:
```
const Lru = require('toad-cache').Lru
```
correct:
```
import { Lru } from 'toad-cache'
```
ESM named import is preferred. CommonJS require for classes needs direct property access since v3.0.0.
Fifo
wrong:
```
import Fifo from 'toad-cache'
```
correct:
```
import { Fifo } from 'toad-cache'
```
Both LRU and FIFO caches are named exports; there is no default export. Do not use default import syntax.
LruHitStatistics
wrong:
```
import { Lru, HitStatisticsRecord } from 'toad-cache'
```
correct:
```
import { LruHitStatistics } from 'toad-cache'
```
LruHitStatistics is a separate class for caches requiring hit/miss/expiration tracking, distinct from the base Lru class. HitStatisticsRecord is also a named export for shared statistics.

Quickstart

Demonstrates the instantiation and basic usage of LRU and FIFO caches, including setting, getting, deleting, and integrating with the optional hit/miss/expiration statistics tracking.

import { Lru, Fifo, LruHitStatistics, HitStatisticsRecord } from 'toad-cache';

// Basic LRU Cache
const lruCache = new Lru(100, 5000); // Max 100 items, 5 seconds TTL
lruCache.set('key1', 'value1');
console.log('LRU get key1:', lruCache.get('key1'));
lruCache.set('key2', { data: 'value2' });
console.log('LRU size:', lruCache.size);
lruCache.delete('key1');
console.log('LRU keys after delete:', lruCache.keys());

// Basic FIFO Cache
const fifoCache = new Fifo(50); // Max 50 items
fifoCache.set('fkey1', 'fvalue1');
fifoCache.set('fkey2', 'fvalue2');
console.log('FIFO get fkey1:', fifoCache.get('fkey1'));

// LRU Cache with Hit Statistics
const sharedRecord = new HitStatisticsRecord();
const statsCache = new LruHitStatistics({
  cacheId: 'my-app-cache',
  globalStatisticsRecord: sharedRecord,
  statisticTtlInHours: 1, // Reset stats hourly
  max: 10,
  ttlInMsecs: 10000 // 10 seconds TTL
});

statsCache.set('skey1', 'svalue1');
statsCache.get('skey1'); // Hit
statsCache.get('skey2'); // Miss
console.log('Cache statistics:', sharedRecord.getStatistics()['my-app-cache']);

view raw JSON →