lru.js API documentation

This module provides a simple Least Recently Used cache.

Internally, this uses a Map, which give us insertion-ordering for free. The first item in the list is the oldest. The last item is the most recently set or accessed. Most of the base functionality of the Map are replicated.

Since I don't need it to be super fancy, there isn't a lot of extra functionality here. All the other LRU implementations I looked at were needlessly heavy.

Example usage

import { LRU } from '@slugbugblue/trax/lru.js'

const cache = new LRU(100)

cache.set('a', 1)
cache.set('b', 2)

// Get an item from the cache
console.log(cache.get('a')) // 1

// Accessing a key makes it the most recent:
console.log(cache.keys()) // [Map Iterator] { 'b', 'a' }
console.log(cache.hits) // 1

console.log(cache.get('z')) // undefined
console.log(cache.misses) // 1

console.log(cache.size) // 2
console.log(cache.capacity) // 100

API

LRU class

An LRU cache is a way to remember a limited set of items, with the oldest expiring when the capacity is reached.

constructor

new LRU(capacity)

Create the cache by specifying the maximum number of items it should hold.

computed properties

capacity

The maximum number of items the cache can hold. This cannot be changed after the cache creation.

size

The number of items currently stored in the cache.

hits

The number of times a get call has found an item in the cache.

misses

The number of times a get call has not found an item in the cache.

expired

The number of times an item has been removed from the cache.

methods

get(key)

Retrieve an item from the cache. If the item is found in the cache, hits will be updated, the item will be marked as the most-recently-used item, and the value will be returned. If the item is not present in the cache, misses will be updated, and undefined will be returned.

Note that if you had stored undefined as the value in the cache, the return of undefined doesn't necessarily represent a cache miss.

peek(key)

Retrieve an item from the cache, if present, but without updating any of the LRU-specific information about the retrieval attempt. The item's age will not be updated. If the item is not present in the cache, undefined will be returned.

set(key, value)

Store an item in the cache. If the item is already present in the cache, it will be replaced and marked as the most-recently-used item.

delete(key)

Remove an item from the cache.

clear()

Clears all items and statistics from the cache. The maximum capacity will not change.

entries()

Returns an iterator that operates over all the [key, value] pairs stored in the cache. The entries will be in order from oldest to newest.

has(key)

Returns true if a key is found in the cache, false otherwise.

keys()

Returns an iterator that operates over all the keys stored in the cache. The keys will be returned oldest first, newest last.

values()

Returns an iterator that operates over all the values stored in the cache. The values will be returned oldest first, newest last.

Plays well with others

The LRU class also includes functionality to provide useful default results when used in other contexts.

toString()

Returns a string representation of the cache in the format LRU(75 of 1000). This allows simple logging calls with console.log(cache).

util.inspect.custom()

When running in the node command line interpreter, an LRU cache instance will be pretty-printed using the magic of util.inspect.

License

Copyright 2023 Chad Transtrum

Licensed under the Apache License, Version 2.0 (the "License"); you may not use the files in this project except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.