feat: Add Redis v8 client support, numeric operations, graceful shutdown, and sync functionality to sharded cache with updated documentation.

Author: mysamimi

README.md

@@ -1,35 +1,29 @@
-I forked this project from github.com/patrickmn/go-cache and modified this
-I want to be able to increment/decriment and if not found set it in my case
 # go-cache
+
 ![Go](https://github.com/mysamimi/go-cache/actions/workflows/test.yml/badge.svg)
 [![Go Report Card](https://goreportcard.com/badge/github.com/mysamimi/go-cache/v3)](https://goreportcard.com/report/github.com/mysamimi/go-cache/v3)
 [![Go Reference](https://pkg.go.dev/badge/github.com/mysamimi/go-cache/v3.svg)](https://pkg.go.dev/github.com/mysamimi/go-cache/v3)
 
-go-cache is an in-memory key:value store/cache similar to memcached that is
-suitable for applications running on a single machine. Its major advantage is
-that, being essentially a thread-safe `map[string]interface{}` with expiration
-times, it doesn't need to serialize or transmit its contents over the network.
+go-cache is an in-memory key:value store/cache similar to memcached that is suitable for applications running on a single machine. Its major advantage is that, being essentially a thread-safe `map[string]interface{}` with expiration times, it doesn't need to serialize or transmit its contents over the network.
 
 **Key Features:**
+
 *   **Sharding**: Reduces lock contention for high-concurrency workloads.
-*   **Redis Integration**: Optional L2 caching and persistence layer (fallback on miss, async write).
+*   **Redis Integration**: Optional L2 caching and persistence layer using `go-redis` (supports v8 and v9).
 *   **Capacity Management**: Internal LRU-like eviction when memory limits are reached.
 *   **Generics**: Type-safe API (Go 1.18+).
-
-Any object can be stored, for a given duration or forever, and the cache can be
-safely used by multiple goroutines.
-
-Although go-cache isn't meant to be used as a persistent datastore, the entire
-cache can be saved to and loaded from a file (using `c.Items()` to retrieve the
-items map to serialize, and `NewFrom()` to create a cache from a deserialized
-one) to recover from downtime quickly. (See the docs for `NewFrom()` for caveats.)
+*   **Numeric Operations**: Atomic increment/decrement support for numeric types, persisted to Redis.
+*   **Graceful Shutdown**: Ensures pending Redis operations are completed before exit.
+*   **Sync**: Force refresh items from Redis.
 
 ### Installation
 
 `go get github.com/mysamimi/go-cache/v3`
 
 ### Usage
 
+#### Basic Cache
+
 ```go
 import (
 	"fmt"
@@ -45,11 +39,6 @@ func main() {
 	// Set the value of the key "foo" to "bar", with the default expiration time
 	c.Set("foo", "bar", cache.DefaultExpiration)
 
-	// Set the value of the key "baz" to "yes", with no expiration time
-	// (the item won't be removed until it is re-set, or removed using
-	// c.Delete("baz")
-	c.Set("baz", "yes", cache.NoExpiration)
-
 	// Get the string associated with the key "foo" from the cache
 	foo, found := c.Get("foo")
 	if found == cache.Found {
@@ -58,46 +47,87 @@ func main() {
 }
 ```
 
-### Redis Integration (L2 Cache)
+#### Sharded Cache (Recommended for High Concurrency)
 
-You can configure a Redis client to act as a Level 2 cache and persistent store. Writes are asynchronous to Redis, while reads fallback to Redis if the key is missing from memory.
+`ShardedCache` automatically partitions keys into multiple buckets to reduce lock contention.
 
 ```go
-import "github.com/redis/go-redis/v9"
-
-rdb := redis.NewClient(&redis.Options{
-    Addr: "localhost:6379",
-})
+// Create a sharded cache with 16 shards
+c := cache.NewShardedCache[string](16, 5*time.Minute, 10*time.Minute)
 
-c := cache.New[MyStruct](5*time.Minute, 10*time.Minute)
-c.WithRedis(rdb)
+c.Set("foo", "bar", 0)
+val, found := c.Get("foo")
 ```
 
-### Capacity & Eviction
+#### Redis Integration (L2 Cache & Persistence)
+
+You can configure a Redis client to act as a Level 2 cache and persistent store. Writes (Set/Delete/ModifyNumeric) are asynchronous to Redis, while reads look up Redis if the key is missing from memory.
 
-You can set a maximum number of items for the local in-memory cache.
+Supports both `go-redis/v8` and `go-redis/v9` via adapters.
 
 ```go
-c.WithCapacity(1000)
+import (
+    "github.com/redis/go-redis/v9"
+    "github.com/mysamimi/go-cache/v3"
+    redisv9 "github.com/mysamimi/go-cache/v3/redis/v9"
+)
+
+func main() {
+    // 1. Initialize Redis Client
+    rdb := redis.NewClient(&redis.Options{
+        Addr: "localhost:6379",
+    })
+
+    // 2. Create Cache
+    c := cache.NewShardedCache[MyStruct](16, 5*time.Minute, 10*time.Minute)
+
+    // 3. Enable Redis Integration with Adapter
+    c.WithRedis(redisv9.New(rdb))
+    
+    // 4. Use Cache
+    // This will asynchronously write to Redis
+    c.Set("key", MyStruct{Val: 1}, 0)
+    
+    // 5. Graceful Shutdown
+    // Ensures all pending Redis writes are flushed before exit
+    defer c.Close()
+}
 ```
 
-**Bulk Eviction Strategy**: When the cache reaches the configured capacity, it automatically triggers a bulk eviction, removing random items until the cache size drops to **75%** of the capacity. This prevents "thrashing" (constant delete/add cycles) under heavy load.
+#### Sync from Redis
+
+If you know an item has changed in Redis (e.g. by another service) and want to refresh the local cache immediately:
 
+```go
+val, err := c.Sync("key")
+```
 
-### ShardedCache
+#### Capacity & Aviction
 
-For high concurrency scenarios, you can use `ShardedCache` to reduce lock contention. `ShardedCache` automatically partitions keys into multiple buckets.
+Set a maximum number of items for the local cache. When the limit is reached, items are evicted (approx 25% of cache is cleared) to prevent thrashing.
 
 ```go
-// Create a sharded cache with 16 shards
-c := cache.NewShardedCache[string](16, 5*time.Minute, 10*time.Minute)
+// Limit local cache to 1000 items (distributed across shards)
+c.WithCapacity(1000)
 
-// ShardedCache also supports Redis and Capacity configuration
-c.WithRedis(rdb)
+// Register a callback for when items are evicted (due to expiry or capacity)
+c.OnEvicted(func(k string, v MyStruct) {
+    fmt.Printf("Item %s evicted\n", k)
+})
+```
 
-// Capacity is distributed across shards (e.g. 1000 total / 16 shards)
-c.WithCapacity(1000)
+#### Numeric Operations
 
-c.Set("foo", "bar", 0)
-val, found := c.Get("foo")
+For counters and numeric values, use `NumericCache` (or `ShardedNumericCache`). Operations are atomic and persisted to Redis.
+
+```go
+// Create a Sharded Numeric Cache for int64
+nc := cache.NewShardedNumeric[int64](16, 5*time.Minute, 10*time.Minute)
+nc.WithRedis(redisv9.New(rdb))
+
+// Increment "counter" by 1
+newVal, err := nc.ModifyNumeric("counter", 1, true)
+
+// Decrement "counter" by 5
+newVal, err = nc.ModifyNumeric("counter", 5, false)
 ```

cache.go

@@ -17,6 +17,7 @@ import (
 type RedisClient interface {
 	Get(ctx context.Context, key string) ([]byte, error)
 	Set(ctx context.Context, key string, value any, expiration time.Duration) error
+	Del(ctx context.Context, key string) error
 	TTL(ctx context.Context, key string) (time.Duration, error)
 }
 
@@ -66,12 +67,21 @@ type cache[V any] struct {
 	redisCh       chan redisItem[V]
 	localCapacity int
 	ctx           context.Context
+	wg            sync.WaitGroup
 }
 
+type redisOp int
+
+const (
+	redisOpSet redisOp = iota
+	redisOpDel
+)
+
 type redisItem[V any] struct {
-	k string
-	v V
-	d time.Duration
+	k  string
+	v  V
+	d  time.Duration
+	op redisOp
 }
 
 // Add an item to the cache, replacing any existing item. If the duration is 0
@@ -103,7 +113,7 @@ func (c *cache[V]) set(k string, x V, d time.Duration) {
 	if c.redisClient != nil && c.redisCh != nil {
 		// Use non-blocking send or buffered
 		select {
-		case c.redisCh <- redisItem[V]{k: k, v: x, d: d}:
+		case c.redisCh <- redisItem[V]{k: k, v: x, d: d, op: redisOpSet}:
 		default:
 			// Channel full, drop write to avoid blocking app
 		}
@@ -117,6 +127,12 @@ func (c *cache[V]) evict() {
 		// Target size is 75% of capacity
 		target := c.localCapacity * 3 / 4
 		for k := range c.items {
+			// Check if we need to call OnEvicted
+			if c.onEvicted != nil {
+				if v, found := c.items[k]; found {
+					c.onEvicted(k, v.Object)
+				}
+			}
 			delete(c.items, k)
 			if len(c.items) <= target {
 				break
@@ -241,6 +257,22 @@ func (c *cache[V]) getFallbackWithExpiration(k string) (V, time.Time, bool) {
 	return zero, time.Time{}, false
 }
 
+// Sync fetches the value for the given key from Redis (if available) and updates the local cache.
+// It returns the value and an error if the key was not found in Redis or if Redis is not configured.
+func (c *cache[V]) Sync(k string) (V, error) {
+	val, ttl, found := c.fetchFromRedis(k)
+	if !found {
+		var zero V
+		return zero, fmt.Errorf("item %s not found in Redis", k)
+	}
+
+	c.mu.Lock()
+	c.setLocal(k, val, ttl)
+	c.mu.Unlock()
+
+	return val, nil
+}
+
 func (c *cache[V]) get(k string) (V, bool) {
 	item, found := c.items[k]
 	if !found {
@@ -382,6 +414,26 @@ func (c *NumericCache[N]) ModifyNumeric(k string, operand N, isIncrement bool) (
 	item.Object = newVal
 	c.items[k] = item
 	c.mu.Unlock()
+
+	// Async Redis Write
+	if c.redisClient != nil && c.redisCh != nil {
+		// Calculate remaining TTL
+		var d time.Duration
+		if !item.Expiration.IsZero() {
+			d = time.Until(item.Expiration)
+			if d < 0 {
+				d = 1 * time.Second // Expire immediately?
+			}
+		} else {
+			d = -1 // NoExpiration
+		}
+
+		select {
+		case c.redisCh <- redisItem[N]{k: k, v: newVal, d: d, op: redisOpSet}:
+		default:
+		}
+	}
+
 	return newVal, nil
 }
 
@@ -399,21 +451,24 @@ func (c *cache[V]) delete(k string) (V, bool) {
 	if c.onEvicted != nil {
 		if v, found := c.items[k]; found {
 			delete(c.items, k)
-			// Also call onEvicted here if we are deleting an item that has an onEvicted callback
-			// However, the current logic in Delete() and DeleteExpired() calls onEvicted *after*
-			// the lock is released, based on the collected items.
-			// For consistency with that pattern, we might not call it here directly,
-			// or the calling functions (Delete, DeleteExpired) must be aware.
-			// The current `Delete` method does:
-			//   c.mu.Lock()
-			//   v, evicted := c.delete(k)
-			//   c.mu.Unlock()
-			//   if evicted { c.onEvicted(k, v) }
-			// This implies c.delete should just return the value and a flag.
+			// Redis Async Delete
+			if c.redisClient != nil && c.redisCh != nil {
+				select {
+				case c.redisCh <- redisItem[V]{k: k, op: redisOpDel}:
+				default:
+				}
+			}
 			return v.Object, true
 		}
 	}
 	delete(c.items, k)
+	// Redis Async Delete (even if onEvicted is nil)
+	if c.redisClient != nil && c.redisCh != nil {
+		select {
+		case c.redisCh <- redisItem[V]{k: k, op: redisOpDel}:
+		default:
+		}
+	}
 	var zero V
 	return zero, false
 }
@@ -648,21 +703,38 @@ func (c *cache[V]) withCapacity(cap int) {
 }
 
 func (c *cache[V]) redisWorker() {
+	defer c.wg.Done()
 	for item := range c.redisCh {
 		if c.redisClient != nil {
-			// Serialize/Marshal is handled by go-redis if we pass structs?
-			// go-redis handles basic types. For generic V, we might need to marshal.
-			// But go-redis Set accepts 'any'. It uses internal formatting.
-			// If V is a struct, it uses fmt.Sprint by default or implements BinaryMarshaler.
-			// It's safer to marshal to JSON explicitly to ensure we can unmarshal back.
-			data, err := json.Marshal(item.v)
-			if err == nil {
-				c.redisClient.Set(c.ctx, item.k, data, item.d)
+			switch item.op {
+			case redisOpSet:
+				// Serialize/Marshal is handled by go-redis if we pass structs?
+				// go-redis handles basic types. For generic V, we might need to marshal.
+				// But go-redis Set accepts 'any'. It uses internal formatting.
+				// If V is a struct, it uses fmt.Sprint by default or implements BinaryMarshaler.
+				// It's safer to marshal to JSON explicitly to ensure we can unmarshal back.
+				data, err := json.Marshal(item.v)
+				if err == nil {
+					c.redisClient.Set(c.ctx, item.k, data, item.d)
+				}
+			case redisOpDel:
+				c.redisClient.Del(c.ctx, item.k)
 			}
 		}
 	}
 }
 
+// Close stops the background Redis worker and waits for pending operations to complete.
+func (c *cache[V]) Close() {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+	if c.redisCh != nil {
+		close(c.redisCh)
+		c.redisCh = nil
+	}
+	c.wg.Wait()
+}
+
 // Configures the cache to use a Redis client for L2 caching and async persistence.
 // This also starts the async worker for Redis writes.
 func (c *Cache[V]) WithRedis(cli RedisClient) *Cache[V] {
@@ -677,6 +749,7 @@ func (c *cache[V]) withRedis(cli RedisClient) {
 	if c.redisCh == nil {
 		c.redisCh = make(chan redisItem[V], 1000) // Buffer for async writes
 		c.ctx = context.Background()              // Or accept context
+		c.wg.Add(1)
 		go c.redisWorker()
 	}
 }

cache_redis_test.go

@@ -22,6 +22,10 @@ func (r *RedisAdapter) Set(ctx context.Context, key string, value any, expiratio
 	return r.client.Set(ctx, key, value, expiration).Err()
 }
 
+func (r *RedisAdapter) Del(ctx context.Context, key string) error {
+	return r.client.Del(ctx, key).Err()
+}
+
 func (r *RedisAdapter) TTL(ctx context.Context, key string) (time.Duration, error) {
 	return r.client.TTL(ctx, key).Result()
 }

go.mod

@@ -2,7 +2,10 @@ module github.com/mysamimi/go-cache/v3
 
 go 1.24
 
-require github.com/redis/go-redis/v9 v9.17.3
+require (
+	github.com/go-redis/redis/v8 v8.11.5
+	github.com/redis/go-redis/v9 v9.17.3
+)
 
 require (
 	github.com/cespare/xxhash/v2 v2.3.0 // indirect