🔒 SmartCache

A garbage-collection-aware, WeakRef-powered cache for long-running apps.

SmartCache is a memory-efficient in-memory cache built with WeakRef and FinalizationRegistry. It automatically cleans up values when they are garbage collected, helping you avoid memory leaks in high-uptime applications like servers, data processors, or editor tools.

🚀 Features

🧠 Garbage collection-aware with WeakRef and FinalizationRegistry
🔑 Supports both object and symbol values
🧼 Automatic cleanup of dead entries
🔍 Utility methods: .get(), .has(), .delete(), .clear(), .keys(), .size
⏳ Optional TTL (Time-To-Live) expiration
📉 maxSize support with LRU eviction strategy
🧪 Fully unit tested (with GC-safe behavior)

📦 Installation

npm install smart-cache-gc

SmartCache works out of the box with optional ttl and maxSize for expiration and LRU eviction.

🛠️ Usage

import { SmartCache } from 'smart-cache-gc'

// Optional TTL and maxSize support
const cacheWithOptions = new SmartCache<object>({
  defaultTtl: 1000 * 60, // 1 minute TTL by default
  maxSize: 100           // LRU eviction after 100 items
})

let obj = { id: 1 }
const key = { customKey: true }

cache.set(key, obj)

console.log(cache.has(key)) // true
console.log(cache.get(key)) // { id: 1 }

// Simulate garbage collection
obj = null
global.gc?.()

setTimeout(() => {
console.log(cache.get(key)) // null (after GC)
}, 500)

📚 Examples

For comprehensive examples and real-world use cases, check out the examples directory in this repository:

Basic Usage - Getting started with SmartCache
Advanced Configuration - Complex scenarios and best practices
Performance Benchmarks - Testing memory efficiency

🔔 GC Cleanup Hook

You can register a cleanup callback for when an object is garbage collected:

cache.getNotificationOnGC({
  key,
  value: yourObject,
  cleanup: (key, value) => {
    console.log(`${String(key)} was garbage collected`)
  }
})

🧪 Testing

node --expose-gc node_modules/vitest/vitest.mjs run

📁 Methods

Method	Description
`set(key, value)`	Store a value under a key (object or symbol)
`get(key)`	Get cached value or `null` if GC'd
`has(key)`	Returns `true` if value is alive
`delete(key)`	Removes an entry
`clear()`	Clears all entries
`keys()`	Returns all alive keys
`size` (getter)	Number of alive entries
`getNotificationOnGC`	Register a GC cleanup callback for a value

⚙️ Constructor Options

Option	Description
`defaultTtl`	Default time-to-live for entries (in ms)
`maxSize`	Maximum number of live entries before eviction

🕒 ttl per-entry (override)

You can override the default TTL on a per-entry basis using the optional ttl in .set():

cache.set(key, value, { ttl: 5000 }) // expires in 5 seconds

This overrides the defaultTtl set in the constructor (if any) for this specific entry only.

♻️ LRU Eviction

When maxSize is defined, SmartCache uses an optimized LRU eviction policy to remove the least recently accessed entries. This keeps memory usage predictable in high-load scenarios.

Support

⚠️ This package requires support for WeakRef and FinalizationRegistry. These are available in:

Chrome 84+

Firefox 79+

Node.js 14.6+

Safari: Not yet supported as of 2025

Please ensure your environment supports these features.

📜 License

MIT

🤝 Contributing

Feel free to open issues or pull requests!

Author

Made with care by Milan Panta