cache

Functional cache utilities.

Documentation

Example

import{Cache}from"@monstermann/cache";// Create a LRU cache with a maximum of 100 itemsconstcache=Cache.LRU<string,number>({max: 100});// Set valuesCache.set(cache,"foo",1);Cache.set(cache,"bar",2);// Get valuesconstfoo=Cache.get(cache,"foo");// 1constmissing=Cache.get(cache,"unknown");// undefined// Get or compute and cache a valueconstscore=Cache.getOrElse(cache,"baz",(c)=>{returnCache.set(c,"baz",3);});// Check existenceCache.has(cache,"foo");// true// Remove valuesCache.remove(cache,"bar");

Installation

npm install @monstermann/cache

pnpm add @monstermann/cache

yarn add @monstermann/cache

bun add @monstermann/cache

Tree-shaking

Installation

npm install -D @monstermann/unplugin-cache

pnpm -D add @monstermann/unplugin-cache

yarn -D add @monstermann/unplugin-cache

bun -D add @monstermann/unplugin-cache

Usage

// vite.config.tsimportcachefrom"@monstermann/unplugin-cache/vite";exportdefaultdefineConfig({plugins: [cache()],});

// rollup.config.jsimportcachefrom"@monstermann/unplugin-cache/rollup";exportdefault{plugins: [cache()],};

// rolldown.config.jsimportcachefrom"@monstermann/unplugin-cache/rolldown";exportdefault{plugins: [cache()],};

// webpack.config.jsconstcache=require("@monstermann/unplugin-cache/webpack");module.exports={plugins: [cache()],};

// rspack.config.jsconstcache=require("@monstermann/unplugin-cache/rspack");module.exports={plugins: [cache()],};

// esbuild.config.jsimport{build}from"esbuild";importcachefrom"@monstermann/unplugin-cache/esbuild";build({plugins: [cache()],});

Cache

get

functionCache.get(cache: Cache<K,V>,key: K): V|undefined

Gets a value from the cache by key, returning undefined if the key doesn't exist.

Example

import{Cache}from"@monstermann/cache";constcache=Cache.Map<string,number>();Cache.set(cache,"foo",42);Cache.get(cache,"foo");// 42Cache.get(cache,"bar");// undefined

getAll

functionCache.getAll(cache: Cache<K,V>,keys: Iterable<K>): (V|undefined)[]

Gets multiple values from the cache by keys, returning an array where each element is either the value or undefined if the key doesn't exist.

Example

import{Cache}from"@monstermann/cache";constcache=Cache.Map<string,number>();Cache.set(cache,"foo",42);Cache.set(cache,"bar",100);Cache.getAll(cache,["foo","bar","baz"]);// [42, 100, undefined]

getAllOr

functionCache.getAllOr(cache: Cache<K,V>,keys: Iterable<K>,or: T): (V|T)[]

Gets multiple values from the cache by keys, returning an array where each element is either the value or the fallback value if the key doesn't exist.

Example

import{Cache}from"@monstermann/cache";constcache=Cache.Map<string,number>();Cache.set(cache,"foo",42);Cache.set(cache,"bar",100);Cache.getAllOr(cache,["foo","bar","baz"],0);// [42, 100, 0]

getAllOrElse

functionCache.getAllOrElse(cache: Cache<K,V>,keys: Iterable<K>,orElse: (cache: Cache<K,V>,key: K)=>T): (V|T)[]

Gets multiple values from the cache by keys, calling the fallback function for each missing key. Useful for lazy computation or setting default values in the cache.

Example

import{Cache}from"@monstermann/cache";constcache=Cache.Map<string,number>();Cache.set(cache,"foo",42);Cache.set(cache,"bar",100);Cache.getAllOrElse(cache,["foo","bar","baz"],()=>0);// [42, 100, 0]// Set default values for missing keysCache.getAllOrElse(cache,["foo","qux","quux"],(c,key)=>{returnCache.set(c,key,key.length);});// [42, 3, 4]

getAllOrThrow

functionCache.getAllOrThrow(cache: Cache<K,V>,keys: Iterable<K>): V[]

Gets multiple values from the cache by keys, throwing an error if any key doesn't exist.

Example

import{Cache}from"@monstermann/cache";constcache=Cache.Map<string,number>();Cache.set(cache,"foo",42);Cache.set(cache,"bar",100);Cache.getAllOrThrow(cache,["foo","bar"]);// [42, 100]Cache.getAllOrThrow(cache,["foo","baz"]);// throws Error

getOr

functionCache.getOr(cache: Cache<K,V>,key: K,or: T): V|T

Gets a value from the cache by key, returning the fallback value if the key doesn't exist.

Example

import{Cache}from"@monstermann/cache";constcache=Cache.Map<string,number>();Cache.set(cache,"foo",42);Cache.getOr(cache,"foo",0);// 42Cache.getOr(cache,"bar",0);// 0

getOrElse

functionCache.getOrElse(cache: Cache<K,V>,key: K,orElse: (cache: Cache<K,V>)=>T): V|T

Gets a value from the cache by key, calling the fallback function if the key doesn't exist. Useful for lazy computation or setting a default value in the cache.

Example

import{Cache}from"@monstermann/cache";constcache=Cache.Map<string,number>();Cache.set(cache,"foo",42);Cache.getOrElse(cache,"foo",()=>0);// 42Cache.getOrElse(cache,"bar",()=>0);// 0// Set default value if missingCache.getOrElse(cache,"baz",(c)=>{returnCache.set(c,"baz",100);});// 100

getOrThrow

functionCache.getOrThrow(cache: Cache<K,V>,key: K): V

Gets a value from the cache by key, throwing an error if the key doesn't exist.

Example

import{Cache}from"@monstermann/cache";constcache=Cache.Map<string,number>();Cache.set(cache,"foo",42);Cache.getOrThrow(cache,"foo");// 42Cache.getOrThrow(cache,"bar");// throws Error

has

functionCache.has(cache: Cache<K,V>,key: K): boolean

Checks if a key exists in the cache.

Example

import{Cache}from"@monstermann/cache";constcache=Cache.Map<string,number>();Cache.set(cache,"foo",42);Cache.has(cache,"foo");// trueCache.has(cache,"bar");// false

hasAll

functionCache.hasAll(cache: Cache<K,V>,keys: Iterable<K>): boolean

Checks if all keys exist in the cache. Returns true only if every key is present.

Example

import{Cache}from"@monstermann/cache";constcache=Cache.Map<string,number>();Cache.set(cache,"foo",42);Cache.set(cache,"bar",100);Cache.hasAll(cache,["foo","bar"]);// trueCache.hasAll(cache,["foo","baz"]);// false

hasAny

functionCache.hasAny(cache: Cache<K,V>,keys: Iterable<K>): boolean

Checks if any of the keys exist in the cache. Returns true if at least one key is present.

Example

import{Cache}from"@monstermann/cache";constcache=Cache.Map<string,number>();Cache.set(cache,"foo",42);Cache.hasAny(cache,["foo","bar"]);// trueCache.hasAny(cache,["baz","qux"]);// false

hasNone

functionCache.hasNone(cache: Cache<K,V>,keys: Iterable<K>): boolean

Checks if none of the keys exist in the cache. Returns true only if every key is absent.

Example

import{Cache}from"@monstermann/cache";constcache=Cache.Map<string,number>();Cache.set(cache,"foo",42);Cache.hasNone(cache,["baz","qux"]);// trueCache.hasNone(cache,["foo","bar"]);// false

remove

functionCache.remove(cache: Cache<K,V>,key: K): void

Removes a key from the cache.

Example

import{Cache}from"@monstermann/cache";constcache=Cache.Map<string,number>();Cache.set(cache,"foo",42);Cache.has(cache,"foo");// trueCache.remove(cache,"foo");Cache.has(cache,"foo");// false

removeAll

functionCache.removeAll(cache: Cache<K,V>,keys: Iterable<K>): void

Removes multiple keys from the cache. Keys that don't exist are silently ignored.

Example

import{Cache}from"@monstermann/cache";constcache=Cache.Map<string,number>();Cache.set(cache,"foo",42);Cache.set(cache,"bar",100);Cache.set(cache,"baz",200);Cache.removeAll(cache,["foo","baz"]);Cache.has(cache,"foo");// falseCache.has(cache,"bar");// trueCache.has(cache,"baz");// false

set

functionCache.set(cache: Cache<K,V>,key: K,value: V): V

Sets a value in the cache and returns the value.

Example

import{Cache}from"@monstermann/cache";constcache=Cache.Map<string,number>();Cache.set(cache,"foo",42);// 42Cache.set(cache,"bar",100);// 100Cache.get(cache,"foo");// 42Cache.get(cache,"bar");// 100

setAll

functionCache.setAll(cache: Cache<K,V>,entries: [K,V][]): void

Sets multiple key-value pairs in the cache at once.

Example

import{Cache}from"@monstermann/cache";constcache=Cache.Map<string,number>();Cache.setAll(cache,[["foo",42],["bar",100],["baz",200],]);Cache.get(cache,"foo");// 42Cache.get(cache,"bar");// 100Cache.get(cache,"baz");// 200

Storage

FIFO

functionCache.FIFO<K,V>(options: {max: numberonHit?: (key: K)=>voidonMiss?: (key: K)=>void}): FIFOCache<K,V>

Creates a cache with a FIFO (First In, First Out) eviction policy backed by a Map. When the cache exceeds max size, the oldest entry is removed.

Properties

• data.entries: The underlying Map instance
• setMax(max): Updates the maximum cache size

Use Cases

• When you want simple, predictable eviction order
• When access patterns don't matter (unlike LRU)
• When you need a bounded cache with minimal overhead

Example

import{Cache}from"@monstermann/cache";constcache=Cache.FIFO<string,number>({max: 3});Cache.set(cache,"a",1);Cache.set(cache,"b",2);Cache.set(cache,"c",3);Cache.set(cache,"d",4);// "a" is evicted (oldest)Cache.has(cache,"a");// falseCache.has(cache,"b");// true// Dynamically adjust max sizecache.setMax(2);// "b" is evictedCache.has(cache,"b");// false

LFU

functionCache.LFU<K,V>(options: {max: numberonHit?: (key: K)=>voidonMiss?: (key: K)=>void}): LFUCache<K,V>

Creates a cache with an LFU (Least Frequently Used) eviction policy backed by a Map and doubly linked list. When the cache exceeds max size, the least frequently accessed entry is removed. Both reads and writes increment the access frequency counter.

Properties

• data.entries: The underlying Map<K, LFUCacheEntry<K, V>> instance
• data.first: The least frequently used entry in the cache
• data.last: The most frequently used entry in the cache
• setMax(max): Updates the maximum cache size

Use Cases

• When you want to keep frequently accessed items in cache regardless of recency
• When access frequency is more important than recency (unlike LRU)
• When hot data has consistent access patterns over time
• Long-running caches where popular items should persist even if not accessed recently

Example

import{Cache}from"@monstermann/cache";constcache=Cache.LFU<string,number>({max: 3});Cache.set(cache,"a",1);Cache.set(cache,"b",2);Cache.set(cache,"c",3);Cache.get(cache,"a");// "a" frequency: 2Cache.get(cache,"a");// "a" frequency: 3Cache.get(cache,"b");// "b" frequency: 2Cache.set(cache,"d",4);// "c" is evicted (least frequently used, frequency: 1)Cache.has(cache,"a");// trueCache.has(cache,"b");// trueCache.has(cache,"c");// falseCache.has(cache,"d");// true// Dynamically adjust max sizecache.setMax(2);// "d" is evicted (lowest frequency)Cache.has(cache,"d");// false

LRU

functionCache.LRU<K,V>(options: {max: numberonHit?: (key: K)=>voidonMiss?: (key: K)=>void}): LRUCache<K,V>

Creates a cache with an LRU (Least Recently Used) eviction policy backed by a Map. When the cache exceeds max size, the least recently accessed entry is removed. Both reads and writes update recency.

Properties

• data.entries: The underlying Map instance
• setMax(max): Updates the maximum cache size

Use Cases

• When you want to keep frequently accessed items in cache
• Standard caching scenarios where hot data should stay cached
• When access patterns have locality (recently used items are likely to be used again)

Example

import{Cache}from"@monstermann/cache";constcache=Cache.LRU<string,number>({max: 3});Cache.set(cache,"a",1);Cache.set(cache,"b",2);Cache.set(cache,"c",3);Cache.get(cache,"a");// Access "a", making it most recentCache.set(cache,"d",4);// "b" is evicted (least recently used)Cache.has(cache,"a");// trueCache.has(cache,"b");// falseCache.has(cache,"c");// true

LRUTTL

functionCache.LRUTTL<K,V>(options: {max: numberttl: numberonHit?: (key: K)=>voidonMiss?: (key: K)=>void}): LRUTTLCache<K,V>

Creates a cache with both LRU (Least Recently Used) eviction and TTL (Time To Live) expiration backed by a Map. Entries are evicted when the cache exceeds max size or when they exceed the ttl duration in milliseconds.

Properties

• data.entries: The underlying Map instance storing entries with timestamps
• evict(): Manually trigger eviction of expired entries
• setMax(max): Updates the maximum cache size
• setTTL(ttl): Updates the TTL duration and evicts expired entries

Use Cases

• When you need time-based expiration in addition to size limits
• When data becomes stale after a certain period

Example

import{Cache}from"@monstermann/cache";constcache=Cache.LRUTTL<string,number>({max: 100,ttl: 5000,// 5 seconds});Cache.set(cache,"a",1);Cache.get(cache,"a");// 1// After 5+ secondsCache.get(cache,"a");// undefined (expired)// Manual evictionCache.set(cache,"b",2);cache.evict();// Remove expired entries// Adjust TTL at runtimecache.setTTL(10000);// 10 seconds

Map

functionCache.Map<K,V>(options?: {onHit?: (key: K)=>voidonMiss?: (key: K)=>void}): MapCache<K,V>

Creates a cache backed by a Map with no eviction policy.

Properties

• data.entries: The underlying Map instance

Use Cases

• When you don't need automatic eviction
• When cache size won't grow unbounded

Example

import{Cache}from"@monstermann/cache";constcache=Cache.Map<string,number>();Cache.set(cache,"foo",42);Cache.set(cache,"bar",100);Cache.get(cache,"foo");// 42// Access underlying Map if neededcache.data.entries.size;// 2

WeakMap

functionCache.WeakMap<KextendsWeakKey,V>(options?: {onHit?: (key: K)=>voidonMiss?: (key: K)=>void}): WeakMapCache<K,V>

Creates a cache backed by a JavaScript WeakMap. Keys must be objects and are held weakly, allowing them to be garbage collected when no other references exist.

Properties

• data.entries: The underlying WeakMap instance

Use Cases

• When you want to associate data with objects without preventing garbage collection
• When you need automatic cleanup of entries when keys are no longer referenced

Example

import{Cache}from"@monstermann/cache";constcache=Cache.WeakMap<object,number>();constobj1={id: 1};constobj2={id: 2};Cache.set(cache,obj1,42);Cache.set(cache,obj2,100);Cache.get(cache,obj1);// 42// When obj1 is no longer referenced elsewhere,// it will be automatically removed from the cache