0
# Caches
1

2
LRU (Least Recently Used) caches with configurable capacity and efficient eviction policies for memory management.
3

4
## Capabilities
5

6
### LRUCache
7

8
Least Recently Used cache with configurable capacity and automatic eviction.
9

10
```typescript { .api }
11
/**
12
 * LRU Cache with configurable key/value types and capacity
13
 * @param Keys Optional key array constructor for typed keys
14
 * @param Values Optional value array constructor for typed values  
15
 * @param capacity Maximum number of items to store
16
 */
17
function LRUCache<K, V>(capacity: number): LRUCache<K, V>;
18
function LRUCache<K, V>(Keys: ArrayConstructor, Values: ArrayConstructor, capacity: number): LRUCache<K, V>;
19

20
interface LRUCache<K, V> {
21
  /** Maximum number of items the cache can hold */
22
  readonly capacity: number;
23
  
24
  /** Current number of items in the cache */
25
  readonly size: number;
26
  
27
  /** Store key-value pair, evicts oldest if at capacity */
28
  set(key: K, value: V): this;
29
  
30
  /** Retrieve value for key, marks as recently used */
31
  get(key: K): V | undefined;
32
  
33
  /** Retrieve value without marking as recently used */
34
  peek(key: K): V | undefined;
35
  
36
  /** Check if key exists in cache */
37
  has(key: K): boolean;
38
  
39
  /** Remove specific key from cache */
40
  delete(key: K): boolean;
41
  
42
  /** Set key-value pair and return evicted item if any */
43
  setpop(key: K, value: V): V | undefined;
44
  
45
  /** Remove all items from cache */
46
  clear(): void;
47
  
48
  /** Iterate over values in LRU order (oldest first) */
49
  values(): IterableIterator<V>;
50
  
51
  /** Iterate over keys in LRU order (oldest first) */
52
  keys(): IterableIterator<K>;
53
  
54
  /** Iterate over [key, value] pairs in LRU order */
55
  entries(): IterableIterator<[K, V]>;
56
  
57
  /** Default iterator (same as entries) */
58
  [Symbol.iterator](): IterableIterator<[K, V]>;
59
  
60
  /** Execute callback for each item in LRU order */
61
  forEach(callback: (value: V, key: K, cache: this) => void): void;
62
  
63
  /** Debug representation */
64
  inspect(): any;
65
}
66
```
67

68
**Usage Examples:**
69

70
```typescript
71
import {LRUCache} from "mnemonist";
72

73
// Basic string cache
74
const cache = new LRUCache<string, any>(100);
75
cache.set("user:123", {name: "Alice", age: 30});
76
cache.set("user:456", {name: "Bob", age: 25});
77

78
const user = cache.get("user:123"); // Marks as recently used
79
console.log(user?.name); // "Alice"
80

81
// Check without affecting LRU order
82
const peeked = cache.peek("user:456");
83

84
// With typed arrays for performance
85
const typedCache = new LRUCache(Array, Array, 1000);
86

87
// Set and get evicted item
88
const evicted = cache.setpop("new_key", "new_value");
89
if (evicted) {
90
  console.log("Evicted:", evicted);
91
}
92

93
// Iteration in LRU order (oldest first)
94
for (const [key, value] of cache) {
95
  console.log(`${key}: ${value}`);
96
}
97
```
98

99
### LRUCacheWithDelete
100

101
LRU Cache optimized for frequent deletions with explicit delete functionality.
102

103
```typescript { .api }
104
/**
105
 * LRU Cache optimized for frequent deletions
106
 * @param capacity Maximum number of items to store
107
 */
108
function LRUCacheWithDelete<K, V>(capacity: number): LRUCacheWithDelete<K, V>;
109

110
interface LRUCacheWithDelete<K, V> {
111
  /** Maximum number of items the cache can hold */
112
  readonly capacity: number;
113
  
114
  /** Current number of items in the cache */
115
  readonly size: number;
116
  
117
  /** Store key-value pair, evicts oldest if at capacity */
118
  set(key: K, value: V): this;
119
  
120
  /** Retrieve value for key, marks as recently used */
121
  get(key: K): V | undefined;
122
  
123
  /** Retrieve value without marking as recently used */
124
  peek(key: K): V | undefined;
125
  
126
  /** Check if key exists in cache */
127
  has(key: K): boolean;
128
  
129
  /** Remove specific key from cache (optimized operation) */
130
  delete(key: K): boolean;
131
  
132
  /** Remove all items from cache */
133
  clear(): void;
134
  
135
  /** Iterate over values in LRU order */
136
  values(): IterableIterator<V>;
137
  
138
  /** Iterate over keys in LRU order */
139
  keys(): IterableIterator<K>;
140
  
141
  /** Iterate over [key, value] pairs in LRU order */
142
  entries(): IterableIterator<[K, V]>;
143
  
144
  /** Default iterator (same as entries) */
145
  [Symbol.iterator](): IterableIterator<[K, V]>;
146
  
147
  /** Execute callback for each item in LRU order */
148
  forEach(callback: (value: V, key: K, cache: this) => void): void;
149
  
150
  /** Debug representation */
151
  inspect(): any;
152
}
153
```
154

155
**Usage Examples:**
156

157
```typescript
158
import {LRUCacheWithDelete} from "mnemonist";
159

160
// Cache optimized for frequent deletions
161
const cache = new LRUCacheWithDelete<string, any>(50);
162

163
// Standard operations
164
cache.set("temp:1", {data: "temporary"});
165
cache.set("temp:2", {data: "also temporary"});
166

167
// Efficient deletion (the key difference)
168
cache.delete("temp:1"); // Optimized for this use case
169

170
// Use when you frequently remove items before they're evicted
171
const sessionCache = new LRUCacheWithDelete<string, SessionData>(1000);
172
sessionCache.set("session123", sessionData);
173
// Later, when session expires:
174
sessionCache.delete("session123"); // Efficient removal
175
```
176

177
### LRUMap
178

179
Map-like LRU cache implementing the standard Map interface.
180

181
```typescript { .api }
182
/**
183
 * Map-like LRU cache with standard Map interface
184
 * @param capacity Maximum number of items to store
185
 */
186
function LRUMap<K, V>(capacity: number): LRUMap<K, V>;
187

188
interface LRUMap<K, V> extends Map<K, V> {
189
  /** Maximum number of items the map can hold */
190
  readonly capacity: number;
191
  
192
  /** Current number of items in the map */
193
  readonly size: number;
194
  
195
  /** Store key-value pair (Map interface) */
196
  set(key: K, value: V): this;
197
  
198
  /** Retrieve value for key (Map interface) */
199
  get(key: K): V | undefined;
200
  
201
  /** Check if key exists (Map interface) */
202
  has(key: K): boolean;
203
  
204
  /** Remove specific key (Map interface) */
205
  delete(key: K): boolean;
206
  
207
  /** Remove all items (Map interface) */
208
  clear(): void;
209
  
210
  /** Retrieve value without marking as recently used */
211
  peek(key: K): V | undefined;
212
  
213
  /** Standard Map iteration methods */
214
  values(): IterableIterator<V>;
215
  keys(): IterableIterator<K>;
216
  entries(): IterableIterator<[K, V]>;
217
  [Symbol.iterator](): IterableIterator<[K, V]>;
218
  forEach(callback: (value: V, key: K, map: this) => void): void;
219
  
220
  /** Debug representation */
221
  inspect(): any;
222
}
223
```
224

225
**Usage Examples:**
226

227
```typescript
228
import {LRUMap} from "mnemonist";
229

230
// Drop-in replacement for Map with LRU eviction
231
const lruMap = new LRUMap<string, number>(100);
232

233
// Standard Map operations
234
lruMap.set("a", 1);
235
lruMap.set("b", 2);
236
console.log(lruMap.get("a")); // 1
237
console.log(lruMap.has("b")); // true
238
console.log(lruMap.size);     // 2
239

240
// LRU-specific operation
241
const peeked = lruMap.peek("a"); // Doesn't affect LRU order
242

243
// Compatible with Map-expecting code
244
function processMap(map: Map<string, number>) {
245
  for (const [key, value] of map) {
246
    console.log(`${key}: ${value}`);
247
  }
248
}
249

250
processMap(lruMap); // Works seamlessly
251
```
252

253
### LRUMapWithDelete
254

255
Map-like LRU cache optimized for frequent deletions.
256

257
```typescript { .api }
258
/**
259
 * Map-like LRU cache optimized for frequent deletions
260
 * @param capacity Maximum number of items to store
261
 */
262
function LRUMapWithDelete<K, V>(capacity: number): LRUMapWithDelete<K, V>;
263

264
interface LRUMapWithDelete<K, V> extends Map<K, V> {
265
  /** Maximum number of items the map can hold */
266
  readonly capacity: number;
267
  
268
  /** Current number of items in the map */
269
  readonly size: number;
270
  
271
  /** Standard Map interface with LRU eviction */
272
  set(key: K, value: V): this;
273
  get(key: K): V | undefined;
274
  has(key: K): boolean;
275
  delete(key: K): boolean; // Optimized operation
276
  clear(): void;
277
  
278
  /** Retrieve value without marking as recently used */
279
  peek(key: K): V | undefined;
280
  
281
  /** Standard Map iteration methods */
282
  values(): IterableIterator<V>;
283
  keys(): IterableIterator<K>;
284
  entries(): IterableIterator<[K, V]>;
285
  [Symbol.iterator](): IterableIterator<[K, V]>;
286
  forEach(callback: (value: V, key: K, map: this) => void): void;
287
  
288
  /** Debug representation */
289
  inspect(): any;
290
}
291
```
292

293
**Usage Examples:**
294

295
```typescript
296
import {LRUMapWithDelete} from "mnemonist";
297

298
// For scenarios with frequent deletions
299
const cache = new LRUMapWithDelete<string, CacheItem>(200);
300

301
// Standard Map operations
302
cache.set("item1", {data: "value1", expires: Date.now() + 60000});
303
cache.set("item2", {data: "value2", expires: Date.now() + 120000});
304

305
// Efficient deletion when items expire
306
setInterval(() => {
307
  const now = Date.now();
308
  for (const [key, item] of cache) {
309
    if (item.expires < now) {
310
      cache.delete(key); // Optimized for this pattern
311
    }
312
  }
313
}, 1000);
314
```
315

316
## Types
317

318
```typescript { .api }
319
/**
320
 * Array constructor types supported by LRUCache for typed storage
321
 */
322
type ArrayConstructor = 
323
  | ArrayConstructor
324
  | Int8ArrayConstructor
325
  | Uint8ArrayConstructor
326
  | Int16ArrayConstructor
327
  | Uint16ArrayConstructor
328
  | Int32ArrayConstructor
329
  | Uint32ArrayConstructor
330
  | Float32ArrayConstructor
331
  | Float64ArrayConstructor;
332
```
333

334
## Performance Characteristics
335

336
| Operation | LRUCache | LRUCacheWithDelete | LRUMap | LRUMapWithDelete |
337
|-----------|----------|-------------------|---------|------------------|
338
| Get | O(1) | O(1) | O(1) | O(1) |
339
| Set | O(1) | O(1) | O(1) | O(1) |
340
| Delete | O(1) | O(1) optimized | O(1) | O(1) optimized |
341
| Peek | O(1) | O(1) | O(1) | O(1) |
342
| Has | O(1) | O(1) | O(1) | O(1) |
343
| Space | O(n) | O(n) | O(n) | O(n) |
344
345
Where n is the cache capacity.
346

347
## Memory Management
348

349
- **Automatic Eviction**: When at capacity, adding new items evicts the least recently used item
350
- **LRU Ordering**: Each access (get/set) moves item to most recently used position
351
- **Peek Operations**: Allow checking values without affecting LRU order
352
- **Typed Storage**: Basic LRUCache supports typed arrays for keys/values to reduce memory overhead
353

354
## Choosing the Right Cache
355

356
- **LRUCache**: General-purpose LRU cache with setpop operation
357
- **LRUCacheWithDelete**: When you frequently remove items before they're evicted naturally
358
- **LRUMap**: When you need standard Map interface compatibility
359
- **LRUMapWithDelete**: Map interface with optimized deletions
360

361
## Common Patterns
362

363
### Web Request Caching
364

365
```typescript
366
const responseCache = new LRUCache<string, Response>(1000);
367

368
async function cachedFetch(url: string): Promise<Response> {
369
  const cached = responseCache.get(url);
370
  if (cached) return cached;
371
  
372
  const response = await fetch(url);
373
  responseCache.set(url, response);
374
  return response;
375
}
376
```
377

378
### Session Management
379

380
```typescript
381
const sessions = new LRUCacheWithDelete<string, SessionData>(10000);
382

383
// Add session
384
sessions.set(sessionId, sessionData);
385

386
// Remove on logout (frequent operation)
387
sessions.delete(sessionId);
388
```
389

390
### Computed Value Caching
391

392
```typescript
393
const memoCache = new LRUMap<string, number>(500);
394

395
function expensiveComputation(input: string): number {
396
  if (memoCache.has(input)) {
397
    return memoCache.get(input)!;
398
  }
399
  
400
  const result = /* expensive calculation */;
401
  memoCache.set(input, result);
402
  return result;
403
}
404
```