LruCache

Example: Basic usage

import { LruCache } from "@ende/cache";
import { assert, assertEquals } from "@ende/assert";

const MAX_SIZE = 3;
const cache = new LruCache<string, number>(MAX_SIZE);

cache.set("a", 1);
cache.set("b", 2);
cache.set("c", 3);
cache.set("d", 4);

// most recent values are stored up to `MAX_SIZE`
assertEquals(cache.get("b"), 2);
assertEquals(cache.get("c"), 3);
assertEquals(cache.get("d"), 4);

// less recent values are removed
assert(!cache.has("a"));

Example: Adding an onEject callback

import { LruCache } from "@ende/cache";
import { assertEquals } from "@ende/assert";

const ejected: [string, number, string][] = [];
const cache = new LruCache<string, number>(2, {
  onEject: (key, value, reason) => ejected.push([key, value, reason]),
});

cache.set("a", 1);
cache.set("b", 2);
cache.set("c", 3);

assertEquals(ejected, [["a", 1, "evicted"]]);

constructor

new LruCache(maxSize: number, options?: LruCacheOptions<K, V>)

experimental

Constructs a new LruCache.

maxSize: number

The maximum number of entries to store in the cache. Must be a positive integer.

options?: LruCacheOptions<K, V>

Additional options.

maxSize

get maxSize(): number

The maximum number of entries to store in the cache.

Returns

The maximum number of entries in the cache.

import { LruCache } from "@ende/cache";
import { assertEquals } from "@ende/assert";

const cache = new LruCache<string, number>(100);
assertEquals(cache.maxSize, 100);

has

has(key: K): boolean

Checks whether an element with the specified key exists or not. Does not update the entry's position in the eviction order.

key: K

The key to check.

Returns

true if the cache contains the specified key, otherwise false.

import { LruCache } from "@ende/cache";
import { assert } from "@ende/assert";

const cache = new LruCache<string, number>(100);

cache.set("a", 1);
assert(cache.has("a"));

get

get(key: K): V | undefined

Gets the element with the specified key.

key: K

The key to get the value for.

Returns

The value associated with the specified key, or undefined if the key is not present in the cache.

import { LruCache } from "@ende/cache";
import { assertEquals } from "@ende/assert";

const cache = new LruCache<string, number>(100);

cache.set("a", 1);
assertEquals(cache.get("a"), 1);

peek

peek(key: K): V | undefined

experimental

Returns the value associated with the given key, or undefined if the key is not present, without updating its position in the eviction order.

key: K

The key to look up.

Returns

The value, or undefined if not present.

import { LruCache } from "@ende/cache";
import { assertEquals } from "@ende/assert";

const cache = new LruCache<string, number>(3);
cache.set("a", 1);
cache.set("b", 2);
cache.set("c", 3);

// peek does not promote "a"
assertEquals(cache.peek("a"), 1);

// "a" is still the least recently used and gets evicted
cache.set("d", 4);
assertEquals(cache.peek("a"), undefined);

set

set(key: K, value: V): this

Sets the specified key to the specified value.

key: K

The key to set the value for.

value: V

The value to set.

Returns

this for chaining.

import { LruCache } from "@ende/cache";

const cache = new LruCache<string, number>(100);
cache.set("a", 1);

delete

delete(key: K): boolean

experimental

Deletes the value associated with the given key.

key: K

The key to delete.

Returns

true if the key was deleted, false otherwise.

import { LruCache } from "@ende/cache";
import { assertEquals } from "@ende/assert/equals";

const cache = new LruCache<string, number>(1);

cache.set("a", 1);
cache.delete("a");
assertEquals(cache.has("a"), false);

clear

clear(): void

experimental

Clears the cache.

import { LruCache } from "@ende/cache";
import { assertEquals } from "@ende/assert/equals";

const cache = new LruCache<string, number>(100);

cache.set("a", 1);
cache.set("b", 2);
cache.clear();
assertEquals(cache.size, 0);