0
# Cache Management
1

2
Advanced cache control features including manual cache manipulation, automatic expiration with pre-fetching, LRU-based size limiting, and reference counting for sophisticated memory management and performance optimization.
3

4
## Capabilities
5

6
### Manual Cache Control
7

8
Direct manipulation of cache entries for fine-grained control over cached results.
9

10
```javascript { .api }
11
/**
12
 * Delete cached result for specific arguments
13
 * @param {...any} args - Arguments to delete from cache (same as function arguments)
14
 */
15
memoizedFunction.delete(...args);
16

17
/**
18
 * Clear all cached results
19
 */
20
memoizedFunction.clear();
21

22
/**
23
 * Get cached value without triggering function execution
24
 * @param {...any} args - Arguments to lookup
25
 * @returns {any} Cached value or undefined if not cached
26
 */
27
memoizedFunction._get(...args);
28

29
/**
30
 * Check if arguments have a cached result
31
 * @param {...any} args - Arguments to check
32
 * @returns {boolean} True if cached result exists
33
 */
34
memoizedFunction._has(...args);
35
```
36

37
**Usage Examples:**
38

39
```javascript
40
const memoize = require("memoizee");
41

42
function expensiveCalculation(x, y) {
43
  console.log(`Computing ${x} * ${y}`);
44
  return x * y;
45
}
46

47
const memoized = memoize(expensiveCalculation);
48

49
// Cache some results
50
memoized(5, 10);  // "Computing 5 * 10", returns 50
51
memoized(3, 7);   // "Computing 3 * 7", returns 21
52

53
// Check cache status
54
console.log(memoized._has(5, 10)); // true
55
console.log(memoized._has(2, 4));  // false
56

57
// Get cached value without execution
58
console.log(memoized._get(5, 10)); // 50 (no console output)
59
console.log(memoized._get(2, 4));  // undefined
60

61
// Delete specific cache entry
62
memoized.delete(5, 10);
63
console.log(memoized._has(5, 10)); // false
64

65
// Clear all cache
66
memoized.clear();
67
console.log(memoized._has(3, 7));  // false
68
```
69

70
### Time-Based Cache Expiration
71

72
Automatically expire cache entries after a specified time period with optional pre-fetching.
73

74
```javascript { .api }
75
/**
76
 * Configure cache expiration
77
 * @param {number} maxAge - Time to live in milliseconds
78
 * @param {boolean|number} preFetch - Pre-fetch configuration
79
 */
80
const options = {
81
  maxAge: number,                    // TTL in milliseconds
82
  preFetch: boolean | number         // Pre-fetch ratio (0-1) or boolean
83
};
84
```
85

86
**Usage Examples:**
87

88
```javascript
89
// Basic cache expiration
90
const memoizedWithTTL = memoize(fetchData, {
91
  maxAge: 60000  // Cache for 1 minute
92
});
93

94
memoizedWithTTL("key");  // Fetches data
95
// ... 30 seconds later
96
memoizedWithTTL("key");  // Returns cached result
97
// ... 70 seconds after first call
98
memoizedWithTTL("key");  // Cache expired, fetches data again
99

100
// Pre-fetching to refresh cache before expiration
101
const memoizedWithPrefetch = memoize(fetchData, {
102
  maxAge: 60000,     // 1 minute TTL
103
  preFetch: true     // Default: refresh when 33% of TTL remains (20 seconds)
104
});
105

106
// Custom pre-fetch timing
107
const customPrefetch = memoize(fetchData, {
108
  maxAge: 60000,
109
  preFetch: 0.8      // Refresh when 80% of TTL elapsed (48 seconds)
110
});
111

112
// Pre-fetching with async functions
113
const asyncMemoized = memoize(asyncFunction, {
114
  async: true,
115
  maxAge: 30000,     // 30 second TTL
116
  preFetch: 0.5      // Refresh at 15 seconds
117
});
118
```
119

120
### LRU Cache Size Limiting
121

122
Limit cache size using Least Recently Used (LRU) eviction policy to manage memory usage.
123

124
```javascript { .api }
125
/**
126
 * Configure cache size limit with LRU eviction
127
 * @param {number} max - Maximum number of cache entries
128
 */
129
const options = {
130
  max: number
131
};
132
```
133

134
**Usage Examples:**
135

136
```javascript
137
// Basic size limiting
138
const limitedCache = memoize(expensiveFunction, {
139
  max: 100  // Keep only 100 most recent results
140
});
141

142
// Size limiting with disposal callback
143
const disposableCache = memoize(createResource, {
144
  max: 50,
145
  dispose: (resource) => {
146
    // Clean up evicted resources
147
    if (resource && resource.cleanup) {
148
      resource.cleanup();
149
    }
150
    console.log("Resource disposed:", resource.id);
151
  }
152
});
153

154
// Combined with time-based expiration
155
const hybridCache = memoize(fetchUserData, {
156
  max: 200,          // LRU limit
157
  maxAge: 300000,    // 5 minute TTL
158
  dispose: (userData) => {
159
    // Cleanup when evicted OR expired
160
    if (userData.session) userData.session.close();
161
  }
162
});
163
```
164

165
### Reference Counting
166

167
Track cache entry usage and enable manual reference-based cache management.
168

169
```javascript { .api }
170
/**
171
 * Enable reference counting for cache entries
172
 * @param {boolean} refCounter - Enable reference counting
173
 */
174
const options = {
175
  refCounter: boolean
176
};
177

178
/**
179
 * Reference counter methods available on memoized functions
180
 */
181
memoizedFunction.deleteRef(...args);     // Decrement reference, delete if zero
182
memoizedFunction.getRefCount(...args);   // Get current reference count
183
```
184

185
**Usage Examples:**
186

187
```javascript
188
const refMemoized = memoize(createExpensiveResource, {
189
  refCounter: true
190
});
191

192
const resource1 = refMemoized("config-a");  // refs: 1
193
const resource2 = refMemoized("config-a");  // refs: 2 (cache hit)
194
const resource3 = refMemoized("config-a");  // refs: 3 (cache hit)
195

196
// Check reference count
197
console.log(refMemoized.getRefCount("config-a")); // 3
198

199
// Decrement references
200
console.log(refMemoized.deleteRef("config-a"));   // false (refs: 2)
201
console.log(refMemoized.deleteRef("config-a"));   // false (refs: 1)
202
console.log(refMemoized.deleteRef("config-a"));   // true (refs: 0, deleted)
203

204
// Resource is now removed from cache
205
console.log(refMemoized.getRefCount("config-a")); // 0
206

207
// Next call will create new resource
208
const newResource = refMemoized("config-a");      // refs: 1 (new instance)
209
```
210

211
### Disposal Callbacks
212

213
Execute cleanup code when cache entries are removed or evicted.
214

215
```javascript { .api }
216
/**
217
 * Configure disposal callback for cache cleanup
218
 * @param {Function} dispose - Callback executed when entries are removed
219
 */
220
const options = {
221
  dispose: function(value) {
222
    // Cleanup logic for cached value
223
  }
224
};
225
```
226

227
**Usage Examples:**
228

229
```javascript
230
// File handle cleanup
231
const memoizedFileOp = memoize(openFile, {
232
  max: 10,  // Limit open files
233
  dispose: (fileHandle) => {
234
    fileHandle.close();
235
    console.log("File closed:", fileHandle.path);
236
  }
237
});
238

239
// Database connection cleanup
240
const memoizedDbQuery = memoize(createDbConnection, {
241
  maxAge: 300000,  // 5 minute connection TTL
242
  dispose: (connection) => {
243
    connection.close();
244
    console.log("Database connection closed");
245
  }
246
});
247

248
// Async disposal with promise functions
249
const promiseMemoized = memoize(asyncResourceFactory, {
250
  promise: true,
251
  max: 20,
252
  dispose: (resource) => {
253
    // Cleanup the resolved value from promises
254
    if (resource && resource.cleanup) {
255
      resource.cleanup();
256
    }
257
  }
258
});
259
```
260

261
## Cache Events
262

263
Advanced cache monitoring through event system for observability and debugging.
264

265
```javascript { .api }
266
/**
267
 * Cache event listeners
268
 */
269
memoizedFunction.on("set", (id, value, result) => {
270
  // Called when value is cached
271
});
272

273
memoizedFunction.on("get", (id, args, context) => {
274
  // Called when value is retrieved from cache
275
});
276

277
memoizedFunction.on("delete", (id, result) => {
278
  // Called when cache entry is deleted
279
});
280

281
memoizedFunction.on("clear", (oldCache) => {
282
  // Called when cache is cleared
283
});
284
```
285

286
**Usage Examples:**
287

288
```javascript
289
const monitoredMemoized = memoize(expensiveFunction, {
290
  max: 100,
291
  maxAge: 60000
292
});
293

294
// Monitor cache performance
295
let cacheHits = 0;
296
let cacheMisses = 0;
297

298
monitoredMemoized.on("get", () => {
299
  cacheHits++;
300
});
301

302
monitoredMemoized.on("set", () => {
303
  cacheMisses++;
304
});
305

306
// Log cache statistics periodically
307
setInterval(() => {
308
  const total = cacheHits + cacheMisses;
309
  const hitRate = total > 0 ? (cacheHits / total * 100).toFixed(2) : 0;
310
  console.log(`Cache hit rate: ${hitRate}% (${cacheHits}/${total})`);
311
}, 10000);
312
```
313

314
## Advanced Cache Management Patterns
315

316
### Cache Warming
317

318
Pre-populate cache with frequently accessed data:
319

320
```javascript
321
const memoized = memoize(expensiveFunction);
322

323
// Warm cache with common inputs
324
const commonInputs = [
325
  [1, 2], [3, 4], [5, 6]
326
];
327

328
commonInputs.forEach(args => {
329
  memoized(...args);  // Populate cache
330
});
331
```
332

333
### Conditional Caching
334

335
Implement custom logic for when to cache results:
336

337
```javascript
338
function conditionalMemoize(fn, shouldCache) {
339
  const memoized = memoize(fn);
340
  const original = memoized;
341
  
342
  return function(...args) {
343
    if (shouldCache(...args)) {
344
      return original(...args);  // Use memoized version
345
    } else {
346
      return fn(...args);        // Call original function
347
    }
348
  };
349
}
350

351
const selectiveMemoized = conditionalMemoize(
352
  expensiveFunction,
353
  (x, y) => x > 10 && y > 10  // Only cache for large inputs
354
);
355
```
356

357
### Cache Hierarchies
358

359
Implement multi-level caching strategies:
360

361
```javascript
362
// L1: Fast, small cache
363
const l1Cache = memoize(expensiveFunction, {
364
  max: 50,
365
  primitive: true
366
});
367

368
// L2: Slower, larger cache with TTL
369
const l2Cache = memoize(expensiveFunction, {
370
  max: 500,
371
  maxAge: 300000
372
});
373

374
function hierarchicalCache(...args) {
375
  // Try L1 first
376
  if (l1Cache._has(...args)) {
377
    return l1Cache(...args);
378
  }
379
  
380
  // Try L2, promote to L1
381
  const result = l2Cache(...args);
382
  l1Cache(...args);  // Store in L1
383
  return result;
384
}
385
```