tlru

library1.1.1jsnpmunverified

Time-aware least recently used (TLRU) cache for Node.js, version 1.1.1. Extends native Map with proactive eviction using a single timer via fun-dispatcher, avoiding linked lists for memory efficiency. Key differentiators: supports per-item TTL, optional LRU mode with maxStoreSize, can revive items on get. Maintained by tinovyatkin. Requires Node >=18, includes TypeScript types.

storage

npm install tlru

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · TLRU

tlru

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.

TLRU

✓ import { TLRU } from 'tlru'

✗ import TLRU from 'tlru'

Named export only. Default import will not work.

TLRU

✓ const { TLRU } = require('tlru')

✗ const TLRU = require('tlru')

CommonJS requires destructuring.

TLRU

✓ import type { TLRU } from 'tlru'

TypeScript type import allowed.

Creates a TLRU cache with max 5 items, each with a default 1 second TTL. Demonstrates set with custom TTL, get, has, and automatic expiration.

import { TLRU } from 'tlru'; const cache = new TLRU({ maxStoreSize: 5, maxAgeMs: 1000 }); cache.set('key1', { data: 'value1' }, 500); // TTL 500ms cache.set('key2', 'value2'); // defaults to 1000ms console.log(cache.get('key1')); // { data: 'value1' } cache.has('key2'); // true setTimeout(() => { console.log(cache.has('key1')); // false (expired) }, 600);

Debug

Known issues

breakingNode.js version requirement is >=18. Older versions are not supported and will cause errors.

fix

Upgrade Node.js to version 18 or later.

affects: >=1.0.0

deprecatedThe 'maxAge' option was deprecated in favor of 'maxAgeMs' in version 1.0.0.

fix

Use maxAgeMs instead of maxAge.

affects: >=1.0.0

gotchaCache eviction is lazy and happens on next timer tick (setImmediate). Checking immediately after set may show stale data.

fix

Wait for setImmediate or setTimeout(0) before relying on evictions for size or keys.

affects: >=1.0.0

gotchaExtending Map: get() returns undefined for missing keys, but also for keys with undefined values. No way to distinguish.

fix

Use has() to check existence, not truthiness of get() result.

affects: >=1.0.0

gotchaTLRU constructor throws if maxStoreSize is not provided when defaultLRU is true.

fix

When using defaultLRU: true, you must provide maxStoreSize.

affects: >=1.0.0

Errors

Common errors & fixes

TLRU is not a constructor

Incorrect import: default import instead of named import.

fix

Use import { TLRU } from 'tlru' instead of import TLRU from 'tlru'.

ERR_REQUIRE_ESM: require() of ES Module not supported

Using CommonJS require with ESM-only version of the package? (tlru supports CJS, but only via require('tlru').)

fix

Ensure using require('tlru') correctly, or switch to import.

TypeError: lru.set is not a function

TLRU is not instantiated; forgetting new keyword.

fix

Use const lru = new TLRU({...});

Upgrade

Version history

1.1.1latest on npm

Audit

Dependencies

fun-dispatcherrequiredUsed internally for timer management

Agent activity

22 hits · last 30 days

node

Resources

githubhttps://github.com/tinovyatkin/tlru ↗

packagetlru ↗

homepagehttps://github.com/tinovyatkin/tlru#readme ↗