tiny-lru

What is tiny-lru?

The tiny-lru npm package is a lightweight, in-memory Least Recently Used (LRU) cache. It is designed to be simple and efficient, making it suitable for use in environments where memory usage and performance are critical.

What are tiny-lru's main functionalities?

Creating an LRU Cache

This feature allows you to create an LRU cache with a specified maximum size. The cache will automatically evict the least recently used items when the size limit is reached.

const LRU = require('tiny-lru');
const cache = LRU(100); // Create a cache with a max size of 100 items

Setting and Getting Cache Items

You can store items in the cache using the `set` method and retrieve them using the `get` method. If the item is not found, `get` will return `undefined`.

cache.set('key', 'value');
const value = cache.get('key'); // 'value'

Deleting Cache Items

This feature allows you to delete specific items from the cache using the `delete` method.

cache.set('key', 'value');
cache.delete('key');
const value = cache.get('key'); // undefined

Clearing the Cache

You can clear all items from the cache using the `clear` method, which removes all entries.

cache.set('key1', 'value1');
cache.set('key2', 'value2');
cache.clear();
const value1 = cache.get('key1'); // undefined
const value2 = cache.get('key2'); // undefined

Cache Size and Item Count

This feature allows you to check the current number of items in the cache using the `size` property.

cache.set('key1', 'value1');
cache.set('key2', 'value2');
const size = cache.size; // 2

Other packages similar to tiny-lru

lru-cache

The lru-cache package is another popular LRU cache implementation for Node.js. It offers more features and configuration options compared to tiny-lru, such as time-to-live (TTL) settings for cache entries and more detailed cache statistics.

quick-lru

The quick-lru package is a minimalist LRU cache implementation that focuses on performance and simplicity. It is similar to tiny-lru in terms of its lightweight nature but offers a slightly different API.

node-cache

The node-cache package provides a simple and efficient in-memory caching solution with support for TTL and other advanced features. It is more feature-rich compared to tiny-lru, making it suitable for more complex caching needs.

README

Tiny LRU

What is Tiny LRU?

Tiny LRU is a tool that helps programs remember things for a short time, so they can work faster and use less memory. It's useful for both websites and apps.

What is a "Cache"?

A cache is like a small, quick-access box where a program stores things it might need again soon. Instead of looking up information from scratch every time (which can be slow), it checks the cache first.

What does "Least Recently Used" (LRU) mean?

Imagine your cache is a box that can only fit a certain number of items. When the box is full and you want to add something new, you remove the item you haven't used in the longest time. This keeps the most recently used things handy, and clears out the old things you don't need anymore.

Why use Tiny LRU?

• Speeds things up: By remembering recent information, programs can respond faster.
• Saves resources: Limits how much memory is used by only keeping the most important items.
• Works anywhere: Can be used in many kinds of apps, big or small.

When is it helpful?

• Websites that show the same info to many people
• Apps that look up data from the internet
• Any program that wants to avoid repeating slow or expensive work

How Does Tiny LRU Work?

• You set a limit for how many things the cache can remember.
• When the program needs to remember something, it puts it in the cache.
• If the cache is full, it removes the oldest unused item to make space.
• If the program needs something, it checks the cache first before doing extra work.

Using the factory

import {lru} from "tiny-lru";
const cache = lru(max, ttl = 0, resetTtl = false);

Using the Class

import {LRU} from "tiny-lru";
const cache = new LRU(max, ttl = 0, resetTtl = false);

import {LRU} from "tiny-lru";
class MyCache extends LRU {}

Interoperability

Lodash provides a memoize function with a cache that can be swapped out as long as it implements the right interface. See the lodash docs for more on memoize.

_.memoize.Cache = lru().constructor;
const memoized = _.memoize(myFunc);
memoized.cache.max = 10;

Testing

Tiny-LRU has 100% code coverage with its tests.

--------------|---------|----------|---------|---------|-------------------
File          | % Stmts | % Branch | % Funcs | % Lines | Uncovered Line #s 
--------------|---------|----------|---------|---------|-------------------
All files     |     100 |    91.46 |     100 |     100 |                   
 tiny-lru.cjs |     100 |    91.46 |     100 |     100 | 11-31,134,181,215 
--------------|---------|----------|---------|---------|-------------------

API Reference

Properties

first

Item in "first" or "bottom" position; default is null

const cache = lru();

cache.first; // null - it's a new cache!

last

Item in "last" or "top" position; default is null

const cache = lru();

cache.last; // null - it's a new cache!

max

Max items to hold in cache; default is 1000

const cache = lru(500);

cache.max; // 500

resetTtl

Resets item.expiry with each set() if true; default is false

const cache = lru(500, 5*6e4, true);

cache.resetTtl; // true

size

Number of items in cache

const cache = lru();

cache.size; // 0 - it's a new cache!

ttl

Milliseconds an item will remain in cache; lazy expiration upon next get() of an item

const cache = lru(100, 3e4);

cache.ttl; // 30000;

Methods

clear

Clears the contents of the cache

return {Object} LRU instance

cache.clear();

delete

Removes item from cache

param  {String} key Item key
return {Object}     LRU instance

cache.delete("myKey");

entries(["key1", "key2"])

Returns an Array cache items

param  {Array} keys (Optional) Cache item keys to get, defaults to `this.keys()` if not provided
return {Object} LRU instance

cache.entries(['myKey1', 'myKey2']);

evict

Evicts the least recently used item from cache

return {Object} LRU instance

cache.evict();

expiresAt

Gets expiration time for cached item

param  {String} key Item key
return {Mixed}      Undefined or number (epoch time)

const item = cache.expiresAt("myKey");

get

Gets cached item and moves it to the front

param  {String} key Item key
return {Mixed}      Undefined or Item value

const item = cache.get("myKey");

has

Returns a Boolean indicating if key is in cache

return {Object} LRU instance

cache.has('myKey');

keys

Returns an Array of cache item keys (first to last)

return {Array} Array of keys

console.log(cache.keys());

set

Sets item in cache as first

param  {String} key   Item key
param  {Mixed}  value Item value
return {Object}       LRU instance

cache.set("myKey", {prop: true});

setWithEvicted

Sets an item in the cache and returns the evicted item if the cache was full and an eviction occurred. If no eviction occurs, returns null.

param  {String} key   Item key
param  {Mixed}  value Item value
param  {Boolean} [resetTtl] Optionally reset the TTL for the item
return {Object|null}  The evicted item (shallow clone) or null

const evicted = cache.setWithEvicted("myKey", {prop: true});
if (evicted) {
  console.log("Evicted item:", evicted.key, evicted.value);
}

values(["key1", "key2"])

Returns an Array cache items

param  {Array} keys (Optional) Cache item keys to get
return {Array} Cache items

cache.values(['abc', 'def']);

License

Copyright (c) 2025 Jason Mulligan Licensed under the BSD-3 license.

Changelog

11.3.2

• Bump rollup from 4.40.2 to 4.41.0 #315
• Fixing missing types file, fixes #316 #316