CacheGraph 1.0.0

CacheGraph 🧠🔗

Cache-aside con grafo de dependencias e invalidación en cascada para .NET

CacheGraph es una librería que combina el patrón cache-aside con un grafo de dependencias entre claves de caché y entidades de negocio, permitiendo invalidación en cascada: al modificar una entidad, todas las claves de caché que dependen de ella se eliminan automáticamente.

📦 Instalación

dotnet add package CacheGraph.Core

✨ Características

• Cache-aside con GetOrSetAsync — carga bajo demanda con factory
• Grafo de dependencias — relaciones cache-key ↔ entidad bidireccionales
• Invalidación en cascada — elimina todas las entradas que dependen de una entidad
• Protección contra stampede — bloqueo distribuido para que solo un hilo ejecute el factory
• 8 interfaces para extender cada componente (cache, grafo, lock, publicador, métricas)
• Eventos — CacheSetEvent, CacheRemovedEvent, EntityInvalidatedEvent
• Métricas — hits, misses, sets, removes, tiempo de operaciones
• Multi-plataforma — .NET 8, .NET 9 y .NET 10
• Sin dependencias externas — solo BCL estándar de .NET

🚀 Inicio rápido

using CacheGraph.Core;
using CacheGraph.Core.Implementaciones;
using CacheGraph.Core.Interfaces;

// Crear el cache graph con implementaciones en memoria
var cacheGraph = new CacheGraph(
    cacheProvider: new MemoryCacheProvider(),
    graphProvider: new MemoryGraphProvider(),
    distributedLock: new MemoryDistributedLock(),
    eventPublisher: new MemoryEventPublisher(),
    metricsRecorder: new MemoryMetricsRecorder(),
    options: new GraphOptions
    {
        DefaultTtl = TimeSpan.FromMinutes(10)
    });

// Registrar entidades en el grafo
await cacheGraph.GraphProvider.AddNodeAsync(
    new Node { Id = "entity:Product:42", Type = NodeType.Entity });

// Cache-aside con dependencias
var product = await cacheGraph.GetOrSetAsync(
    "product:42",
    factory: () => LoadProductFromDbAsync(42),
    dependencies: ["entity:Product:42"],
    ttl: TimeSpan.FromMinutes(5));

// Invalidar entidad → se elimina product:42 automáticamente
await cacheGraph.InvalidateEntityAsync("Product", "42");

// Consultar dependencias y dependientes
var deps = await cacheGraph.GetDependenciesAsync("product:42");
var dependents = await cacheGraph.GetDependentsAsync("entity:Product:42");

🏗️ Arquitectura

┌─────────────────────────────────────────────────┐
│                  CacheGraph                      │
│              ( façade principal )                 │
├──────────┬──────────┬───────────┬────────────────┤
│ ICache   │ IGraph   │ IDistLock │ IEventPublisher│
│ Provider │ Provider │           │                │
├──────────┴──────────┴───────────┴────────────────┤
│              IMetricsRecorder                     │
└─────────────────────────────────────────────────┘

Flujo de datos:

entity:Product:42  ◄────  product:42  ───►  products:featured
                    ▲        (dep)          (dep)
                    │
              cart:user:42
                (dep)

Las aristas van cache-key → entidad (la clave depende de la entidad).

📊 Interfaces disponibles

🧪 Tests

dotnet test

182 tests con xUnit + FluentAssertions, ~88% cobertura.

🎯 Demo

dotnet run --project CacheGraph.Demo

La aplicación de demo muestra todos los escenarios:

• Cache-aside (miss + hit)
• Caché de listados con múltiples dependencias
• Caché de perfil de usuario
• Caché de carrito de compras
• Grafo de dependencias completo
• Invalidación en cascada
• Protección contra stampede

📄 Licencia

MIT License — ver LICENSE para más detalles.