⚡ @omerdev/stash-lru

High-performance O(1) in-memory LRU cache with TTL, sliding expiration, tags, and stats for Node.js, Bun, and browser.

🚀 Features

• Blazing Fast O(1) Operations: Doubly-linked list + Map architecture.
• Flexible TTL: Set global TTL or per-entry TTL.
• Sliding Expiration: Keep hot entries alive by resetting TTL on access.
• Tag-Based Invalidation: Group keys with tags and purge them in bulk (e.g. users, posts:123).
• Stale-While-Revalidate (wrap): Fetch fresh data asynchronously while serving cached values.
• Real-Time Metrics: Track hits, misses, size, and hit ratio.
• Zero Dependencies: Ultra-lightweight (~2KB).

📦 Installation

npm install @omerdev/stash-lru
# or
pnpm add @omerdev/stash-lru
# or
bun add @omerdev/stash-lru

💡 Usage

import { createStash } from "@omerdev/stash-lru";

const cache = createStash<string, any>({
  max: 500,           // Maximum 500 items
  ttl: 1000 * 60 * 5, // 5 minutes default TTL
});

// Set with tags and sliding expiration
cache.set("user:42", { name: "Alice" }, {
  ttl: 1000 * 60,
  sliding: true,
  tags: ["users", "tenant:1"]
});

// Get item
const user = cache.get("user:42");

// Bulk purge by tag
cache.invalidateTag("users");

// Inspect stats
console.log(cache.stats());
// { size: 1, max: 500, hits: 14, misses: 2, hitRatio: 0.875 }

👤 Author

omerdev

📄 License

MIT