Skip to content

lmangani/hyper-lru

Repository files navigation

hyper-lru

Decentralized “Least Recently Used” (LRU) cache

Experimental Fork of Quick-LRU powered by the Hyper Protocol

Hyper-LRU instances can discover each other using DHT topics and exchange cache events with the swarm.

Distributed holepunching through the Hyperswarm DHT

Hyperswarm diagram by @mafintosh

Install

$ npm install hyper-lru

Usage

const HyperLRU = require('hyper-lru');

// Start multiple instances of HyperLRU on different hosts
const lru1 = new HyperLRU({maxSize: 100, hyper: 'mysupersecretlonghash' });
const lru2 = new HyperLRU({maxSize: 100, hyper: 'mysupersecretlonghash' });

// Cache using the 1st LRU
lru1.set('🦄', '🌈');
lru1.has('🦄');
//=> true
lru1.get('🦄');
//=> '🌈'

// Query using the 2nd LRU
lru2.has('🦄');
//=> true
lru2.get('🦄');
//=> '🌈'

API

new HyperLRU(options?)

Returns a new instance.

options

Type: object

maxSize

Required
Type: number

The maximum number of items before evicting the least recently used items.

onEviction

Optional
Type: (key, value) => void

Called right before an item is evicted from the cache.

Useful for side effects or for items like object URLs that need explicit cleanup (revokeObjectURL).

Instance

The instance is an Iterable of [key, value] pairs so you can use it directly in a for…of loop.

Both key and value can be of any type.

.set(key, value)

Set an item. Returns the instance.

.get(key)

Get an item.

.has(key)

Check if an item exists.

.peek(key)

Get an item without marking it as recently used.

.delete(key)

Delete an item.

Returns true if the item is removed or false if the item doesn't exist.

.clear()

Delete all items.

.resize(maxSize)

Update the maxSize, discarding items as necessary. Insertion order is mostly preserved, though this is not a strong guarantee.

Useful for on-the-fly tuning of cache sizes in live systems.

.keys()

Iterable for all the keys.

.values()

Iterable for all the values.

.entriesAscending()

Iterable for all entries, starting with the oldest (ascending in recency).

.entriesDescending()

Iterable for all entries, starting with the newest (descending in recency).

.size

The stored item count.