README

typescript-lru-cache

This is a simple LRU cache implementation written in Typescript. An LRU cache will evict the least recently used item to make room for new items. Useful for when a cache size should be limited but the most used items should be kept.

Installation:

npm i typescript-lru-cache

Why use this LRU Cache?

This library was written in Typescript so type definitions are included out of the box and are always up to date. The Typescript source code is included in the package so users can easily look at the implementation. This cache uses a Map object for internal entry tracking, so any type can be used as a key (including reference types!). Also, this library has no run-time dependencies!

Usage:

See TypeDoc documentation here.

import { LRUCache } from 'typescript-lru-cache';

// Create a cache. Optional options object can be passed in.
const cache = new LRUCache<string, string>();

// Set a value in the cache with a key
cache.set('testKey', 'testValue');

// value will be 'testValue'
const value = cache.get('testKey');
console.log(value);

Options:

LRUCache Options:

Pass in an optional options object into the constructor of the LRU cache.

The options object has the following properties:

export interface LRUCacheOptions<TKey, TValue> {
  maxSize?: number;
  entryExpirationTimeInMS?: number | null;
  onEntryEvicted?: (evictedEntry: { key: TKey; value: TValue; isExpired: boolean }) => void;
  onEntryMarkedAsMostRecentlyUsed?: (entry: { key: TKey; value: TValue }) => void;
  clone?: boolean;
  cloneFn?: (value: TValue) => TValue;
}

maxSize The max number of items the cache can hold. Once the cache reaches this number, the least recently used entries will start to be evicted to make room for new entries. Defaults to 25.
entryExpirationTimeInMS The time to live for cache entries. Setting this to null will make entries never expire. Default value is null.
onEntryEvicted Function to be called whenever an entry is evicted from the cache (when evicted due to needing to make room, is expired, or deleted using delete()). Passed argument is an object:
```
{
  key: TKey;
  value: TValue;
  isExpired: boolean;
}
```
onEntryMarkedAsMostRecentlyUsed Function to be called whenever an entry is marked as recently used (on set, get, find, etc). Passed argument is an object:
```
{
  key: TKey;
  value: TValue;
}
```
clone Clone values being set and fetched from the cache (clones on set and any retrievals). Useful to maintain immutability. NOTE! This does come with performance overhead (almost twice as slow). Defaults to false.
cloneFn Custom function to be used with the clone option. If not passed, JSON.parse(JSON.stringify(value)) is used for cloning objects.

Example using options:

import { LRUCache } from 'typescript-lru-cache';

// Create a cache. Optional options object can be passed in.
const cache = new LRUCache<string, string>({
  maxSize: 100,
  entryExpirationTimeInMS: 5000,
  onEntryEvicted: ({ key, value, isExpired }) =>
    console.log(`Entry with key ${key} and value ${value} was evicted from the cache. Expired: ${isExpired}`),
  onEntryMarkedAsMostRecentlyUsed: ({ key, value }) =>
    console.log(`Entry with key ${key} and value ${value} was just marked as most recently used.`)
});

// Set a value in the cache with a key
cache.set('testKey', 'testValue');

// value will be 'testValue'
const value = cache.get('testKey');
console.log(value);

LRUCache Set Entry Options:

Pass in an optional options object as the third argument of the set method to configure options for just that entry. These options will override LRUCache options if applicable (including callback methods like onEntryEvicted).