toad-cache

library3.7.0jsnpmunverified

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.

http-networking database

npm install toad-cache

github ↗package ↗

INSTALL

IMPORT

SIG · TOAD-CACHE

toad-cache

http-networkingjavascriptv3.7.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Lru

✓ import { Lru } from 'toad-cache'

✗ const Lru = require('toad-cache').Lru

ESM named import is preferred. CommonJS require for classes needs direct property access since v3.0.0.

Fifo

✓ import { Fifo } from 'toad-cache'

✗ 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

✓ import { LruHitStatistics } from 'toad-cache'

✗ import { Lru, HitStatisticsRecord } 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.

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']);

Debug

Known issues

breakingVersion 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'`.

affects: >=3.0.0

gotchaThe `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.

affects: >=1.0.0

gotchaWhen 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.

affects: >=3.1.0

Errors

Common errors & fixes

TypeError: Lru is not a function

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'

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'`.

Upgrade

Version history

3.7.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

19 hits · last 30 days

node

Amazon

OpenAI (training)

Resources

githubhttps://github.com/kibertoad/toad-cache ↗

packagehttps://www.npmjs.com/package/toad-cache ↗