Registry / storage / pixl-cache

pixl-cache

JSON →
library1.1.1jsnpmunverified

Simple LRU (Least Recently Used) cache module for Node.js. Current version 1.1.1 provides a hash-map-backed LRU cache with automatic eviction of least recently used items when max key count or byte size is exceeded. Supports optional item expiration (TTL), custom metadata, event listeners for evictions, and stats tracking. Implemented with a double-linked list for efficient LRU ordering. No external dependencies. Suitable for scenarios requiring a lightweight, predictable caching solution with configurable limits based on item count or byte size. Lower-level and less feature-rich than alternatives like lru-cache, but has zero dependencies and straightforward API.

storage
npm install pixl-cache
github ↗package ↗homepage ↗
INSTALL
IMPORT
SIG · PIXL-CACHE
P
pixl-cache
storagejavascriptv1.1.1
harness data pending
Install & Compatibility
Where this runs

No compatibility data collected yet for this library.

Code
Verified usage

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

LRU
✓ const LRU = require('pixl-cache'); const cache = new LRU();
✗ import LRU from 'pixl-cache';
Package is CommonJS only. Default export is the constructor. ESM import may fail.
LRU
✓ const { LRU } = require('pixl-cache');
✗ import { LRU } from 'pixl-cache';
Named export 'LRU' is available but not the default. Use destructured require.
instance methods
✓ cache.set(key, value); cache.get(key); cache.delete(key); cache.has(key); cache.clear();
✗ cache.set(key, value, ttl);
TTL is set via constructor option maxAge, not per-item on set(). Setting individual TTLs is not supported.

Creates LRU cache with maxItems and shows basic operations: set, get, overflow eviction, delete, clear. Also demonstrates byte limit and TTL configuration.

const LRU = require('pixl-cache'); // Create LRU cache with max 5 items const cache = new LRU({ maxItems: 5 }); // Add items cache.set('key1', 'Simple String'); cache.set('key2', Buffer.alloc(10)); cache.set('key3', { complex: { item: 1234 } }); cache.set('key4', true); cache.set('key5', 'Cache is full now'); // This will evict key1 (LRU) cache.set('key6', 'Oops, key1 is gone now'); // Check eviction console.log(cache.get('key1')); // undefined // Check existence console.log(cache.has('key3')); // true // Manual delete cache.delete('key2'); // Clear all cache.clear(); // Cache with byte limit (1 MB) and TTL (24h) const cache2 = new LRU({ maxBytes: 1048576, maxAge: 86400 }); cache2.set('data', Buffer.alloc(1024 * 512)); // 512KB console.log(cache2.getStats()); // => { items: 1, bytes: 524298, evictions: 0, hits: 1, misses: 0 }
Debug
Known issues
gotchaByte calculation for strings is double the character count (UTF-16). A 10-char string 'ABCDEFGHIJ' counts as 20 bytes.
fix
Account for string byte size as 2x character count when using maxBytes limit.
affects: >=1.0.0
deprecatedThe 'evict' event was renamed to 'expire' in version x.x.x? (not confirmed - check docs). Old event name may still work but is undocumented.
fix
Use cache.on('expire', ...) instead of cache.on('evict', ...).
affects: >=1.0.0
gotchaItem values are stored by reference, not cloned. Mutating an object after cache.set() affects cached value.
fix
Deep clone objects before storing if mutation after set() is a concern.
affects: >=1.0.0
gotchamaxAge timer starts when set() is called, not when item is last accessed. Accessing an item does NOT reset its expiration.
fix
Use manual get-and-set pattern to refresh TTL if needed: cache.set(key, cache.get(key)).
affects: >=1.0.0
gotchaThe byte size includes the key length and value length. Keys are strings; value length depends on type (number=8, boolean=4, string=2*chars).
fix
Consider key length overhead when setting maxBytes. Use short keys to conserve space.
affects: >=1.0.0
Errors
Common errors & fixes
TypeError: LRU is not a constructor
Using ESM import on a CommonJS package.
fix
Use require('pixl-cache') or use dynamic import().default for ESM wrappers.
ReferenceError: require is not defined
Using require() in an ESM context (e.g., Node modules with 'type':'module').
fix
Use createRequire from 'module' or switch to const LRU = (await import('pixl-cache')).default;
Error: getStats is not a function
Calling getStats() on a cache instance with maxItems but no maxBytes? (should still work).
fix
Ensure LRU is properly instantiated: const cache = new LRU(options);
TypeError: cache.on is not a function
Calling .on() on a cache instance but it only exists if initialized with event listeners? (No, .on() is always available).
fix
Check version - pixl-cache 1.x has .on() method. Upgrade if using ancient version.
Upgrade
Version history
1.1.1latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
15 hits · last 30 days
node
14
Amazon
1
Resources
githubhttps://github.com/jhuckaby/pixl-cache ↗
packagepixl-cache ↗
homepagehttps://github.com/jhuckaby/pixl-cache ↗
pixl-cache — npm install pixl-cache · libregistry