cache

type Cache[K comparable, U comparable, V any] interface {
	// Set inserts or replaces an entry. userID is used for bulk invalidation.
	Set(key K, user U, value V, expiry time.Time)

	// Get returns the cached value if present and not expired, updating its access time.
	Get(key K) (V, bool)

	// Delete removes a single entry by key.
	Delete(key K)

	// DeleteByUser removes all entries associated with the given user ID.
	DeleteByUser(user U)

	// Prune removes all expired entries, returning the count removed.
	Prune() int

	// Stats returns a snapshot of cache statistics.
	Stats() CacheStats
}

type CacheStats struct {
	Hits        int64
	Misses      int64
	Evictions   int64 // LRU pressure evictions (max size exceeded)
	Expirations int64 // TTL-based removals via Prune or lazy on Get
	Size        int   // current entry count
}