tinovyatkin/tlru

Time aware least recently used (TLRU) cache for Node

tlru

Time aware least recently used TLRU cache for Node.JS

Small (~ 70 lines of TypeScript), fast (extends native Map class, maintaining the same speed for set, get and has operations), memory efficient (don't uses an internal linked-list for LRU, but instead uses just one timer per class instance via fun-dispatcher and proactively performs cache eviction - so great for caching large objects)

Usage as LRU cache

TLRU may be seen as regular LRU cache where all cached items have the same maxAge as whole cache, and, effectively, this library can be used as efficient LRU cache:

const { TLRU } = require('tlru')

const lru = new TLRU({ defaultLRU: true, maxStoreSize: 2 });

lru.set('a', 1);
lru.set('b', 2);
expect(lru.get('a')).toBe(1);
lru.delete('a');
lru.set('c', 1);
lru.set('d', 1);

// TLRU prunes cache lazily, so, need to give some time
setImmediate(() => {
  expect([...lru.keys()]).toEqual(['c', 'd']);
});

// Peek item without affecting it's LRU rating
lru.get('a', false /* this is the flag */);

// all native `Map` methods are here
lru.delete('a');
console.log([...lru.entries()]); // [[key, value], ...]

// Serializes to JSON, sorted by LRU rating
console.log(JSON.stringify(lru)); // [[key1, value1], [key2, value2], ...]

See more examples at __tests__/lru.test.ts

Usage as TLRU

Each item in cache can have its own TTU (time to usage or time to live).

const { TLRU } = require('tlru')

const lru = new TLRU({ maxStoreSize: 4, maxAgeMs: 1000 });

lru.set('a', 1, 500);
lru.set('b', 2, 700);
lru.set('c', 3); // default TTU = maxAgeMs

setTimeout(() => {
    expect(lru.has('a')).toBeFalsy();
    expect(lru.get('b')).toBe(2);
    expect(lru.has('c')).toBeTruthy();
    expect(lru.size).toBe(2);
}, 600);

setTimeout(() => {
    expect(lru.has('b')).toBeFalsy();
    expect(lru.has('c')).toBeTruthy();
    expect(lru.size).toBe(1);
}, 800);

Items can be revived to original TTU on getting, so, you will have LRU/TRLU hybrid:

const { TLRU } = require('tlru')

const lru = new TLRU({ maxStoreSize: 4, maxAgeMs: 1000 });
lru.set('a', 1, 500);
lru.set('b', 2, 700);
lru.set('c', 3); // default TTU = maxAgeMs

setTimeout(() => {
    expect(lru.has('a')).toBeFalsy();
    expect(lru.get('b', true /* revive flag - reset TTU */)).toBe(2); // 'b' got new 700 ms of life
    expect(lru.size).toBe(2);
}, 600);

setTimeout(() => {
    expect(lru.has('b')).toBeTruthy();
    expect(lru.has('c')).toBeFalsy(); // should be evicted by cache maxAgeMs default
    expect(lru.size).toBe(1);
}, 1200);

setTimeout(() => {
    expect(lru.size).toBe(0);
}, 1500);

tlru's Issues

Citation to TLRU

Thank you for implementing the TLRU scheme. It is always better to give credit to those who first publish an idea. We are the first who come up with this idea and published a research article. Please cite the following article in your about section. Thank you.
M. Bilal and S. Kang, "Time Aware Least Recent Used (TLRU) cache management policy in ICN," 16th International Conference on Advanced Communication Technology, 2014, pp. 528-532, doi: 10.1109/ICACT.2014.6779016.

Action Required: Fix Renovate Configuration

There is an error with this repository's Renovate configuration that needs to be fixed. As a precaution, Renovate will stop PRs until it is resolved.

Error type: undefined. Note: this is a nested preset so please contact the preset author if you are unable to fix it yourself.

Dependency Dashboard

This issue lists Renovate updates and detected dependencies. Read the Dependency Dashboard docs to learn more.

Open

These updates have all been created already. Click a checkbox below to force a retry/rebase of any.

• Update dependency @types/jest to v29.5.8
• Update dependency eslint-plugin-prettier to v5.0.1
• Update babel monorepo to v7.23.3 (@babel/preset-env, @babel/preset-typescript)
• Update dependency @types/node to v18.18.9
• Update dependency eslint to v8.53.0
• Update typescript-eslint monorepo to v6.10.0 (@typescript-eslint/eslint-plugin, @typescript-eslint/parser)
• Update dependency @types/node to v20
• Click on this checkbox to rebase all open PRs at once

Detected dependencies

npm

package.json

• fun-dispatcher ^1.2.6
• @babel/preset-env 7.22.20
• @babel/preset-typescript 7.23.0
• @types/jest 29.5.5
• @types/node 18.17.2
• @typescript-eslint/eslint-plugin 6.9.0
• @typescript-eslint/parser 6.9.0
• eslint 8.51.0
• eslint-config-prettier 9.0.0
• eslint-plugin-prettier 5.0.0
• jest 29.7.0
• jest-junit 16.0.0
• prettier 3.0.3
• typescript 5.2.2
• node >=12.1

---

• Check this box to trigger a request for Renovate to run again on this repository