🧠 DorratCache

DorratCache es una caché adaptable en memoria con soporte para estrategias de eliminación (LRU, LFU), TTL dinámico, persistencia opcional y compatibilidad total con CommonJS y ESM.

🚀 Ideal para bots, middleware, rate-limiters, sesiones y cualquier otro uso que necesite una caché inteligente, flexible y veloz.

---

📦 Requisitos

• Node.js v18 o superior
• Acceso a fs/promises y path (vienen con Node)

---

✨ Características

• ✅ TTL (tiempo de vida) por clave
• ♻️ Adaptación automática del TTL según frecuencia de uso
• 🧠 Estrategia de eliminación:
  • LRU: Least Recently Used (por defecto)
  • LFU: Least Frequently Used
• 💾 Persistencia opcional en disco (JSON)
• 🔧 Compatible con ESM y CommonJS
• 🔥 Sistema de eventos (set, hit, del, clear, evict)
• 🛠️ Tipado completo en TypeScript (.d.ts incluido)

---

🔰 Uso Básico (ESM)

// ESM
import DorratCache from 'dorrat-cache';

const cache = await DorratCache.create({
  max: 100,
  ttl: 60000,
  strategy: 'lru',
  adaptive: true,
  persistence: './cache.json'
});

cache.set('clave', 'valor');
console.log(cache.get('clave')); // "valor"

---

🔰 Uso Básico (CommonJS)

// CommonJS
const { DorratCache } = require('dorrat-cache');

const cache = await DorratCache.create({
  max: 100,
  ttl: 60000,
  strategy: 'lfu',
  adaptive: true,
  persistence: './cache.json'
});

cache.set('clave', 'valor');
console.log(cache.get('clave')); // "valor"

---

🧪 API Pública

new DorratCache(options)

Opción	Tipo	Default	Descripción
max	number	256	Máximo de entradas almacenadas
ttl	number (ms)	60000	Tiempo de vida por defecto por clave
strategy	'lru' / 'lfu' / función personalizada	'lru'	Estrategia de eliminación
adaptive	boolean	true	Aumenta TTL según frecuencia de acceso
persistence	boolean | string	false	Guarda y restaura caché desde disco
serializer	(data) => string	JSON.stringify	Serializador personalizado
deserializer	(raw) => data	JSON.parse	Deserializador personalizado
debounce	number	500	Tiempo de espera para guardar (ms)
evictionRate	number	1	Número de entradas a desalojar extra

---

Métodos

Método	Descripción
set(key, val, ttl?)	Guarda un valor con TTL opcional
get(key, def?)	Obtiene un valor, actualiza hits y TTL si aplica
has(key)	Retorna true si la clave existe y no ha expirado
ttl(key)	Retorna el tiempo restante en ms o -1 si no existe
delete(key)	Elimina una entrada manualmente
clear()	Limpia toda la caché
size()	Retorna la cantidad de claves actuales
keys()	Lista de claves actuales
values()	Lista de valores actuales
entries()	Lista de pares [clave, valor]
snapshot()	Dump actual (serializable) de todo el contenido
[Symbol.iterator]	Iterador para usar en for...of
with(key, fn, ttl?)	Devuelve valor si existe o lo genera y guarda
stop()	Detiene el guardado automático
stats	Objeto con estadísticas: hits, misses, evictions

---

📈 Métricas y extensiones

console.log(cache.stats);
// { hits: 5, misses: 2, evictions: 1 }

await cache.with('user-123', () => getUserFromDB(), 10000);

---

📡 Eventos

Puedes usar .on() para reaccionar a eventos:

cache.on('set', (key, val) => {
  console.log(`📝 Seteado: ${key} =`, val);
});

cache.on('hit', (key, val) => {
  console.log(`🎯 Cache hit: ${key}`);
});

cache.on('del', key => {
  console.log(`🗑️ Eliminado: ${key}`);
});

cache.on('evict', key => {
  console.log(`🚮 Evictado: ${key}`);
});

---

📚 Ejemplo con TTL adaptativo y persistencia

const cache = new DorratCache({
  ttl: 30000,
  adaptive: true,
  persistence: './session-cache.json'
});

cache.set('user123', { online: true });

// Simula acceso frecuente:
setInterval(() => {
  cache.get('user123');
  console.log('TTL:', cache.ttl('user123'));
}, 5000);

---

🗂 Estructura del Proyecto

📁 dorrat-cache
├── esm/
│   └── index.js       → Versión ESM
├── cjs/
│   └── index.cjs      → Versión CommonJS
├── types/
│   └── index.d.ts     → Tipado TypeScript
└── package.json       → Metadata del paquete

---

🧠 Pensado para...

• Bots (WhatsApp, Discord, Telegram)
• APIs y middleware
• Rate-limiting / anti-spam
• Sistemas temporales / TTL
• Caches interactivas con persistencia

---

📜 Licencia

MIT — Hecho con 💖 por DIEGO-OFC

---

📦 Instalar

npm install dorrat-cache

---

💡 Tip

Puedes acceder a la caché como un iterable:

for (const [key, value] of cache) {
  console.log(key, value);
}

---

DorratCache: Simple y rápido.