README.md

Easy-Cache

Easy-Cache is a flexible and efficient caching library written in Go, designed to handle common data structures such as maps, slices, and structs with advanced features like TTL (Time-To-Live), eviction policies, and event-driven invalidation. The library is optimized for performance and supports native caching without the need for JSON serialization, making it ideal for high-performance applications.

Features

• Native Caching: Supports caching of Go's native data structures (map, slice, struct) without the need for JSON serialization.
• TTL (Time-To-Live): Automatically expire cache entries after a specified duration.
• Eviction Policies: Supports Least Recently Used (LRU) and Least Frequently Used (LFU) eviction policies.
• Event-Driven Invalidation: Invalidate cache entries based on custom events.
• Sharded Cache: Scale cache horizontally by sharding data across multiple caches.

Installation

To install Easy-Cache, use the following go get command:

go get github.com/onurbaran/easy-cache

Getting Started

Basic Usage

Here is a basic example of how to use Easy-Cache to cache a simple key-value pair:

package main

import (
    "context"
    "fmt"
    "github.com/onurbaran/easy-cache/pkg/cache"
)

func main() {
    // Create a new cache with default configuration
    config := cache.DefaultConfig()
    c := cache.NewCache(config)

    // Set a value in the cache
    ctx := context.Background()
    c.Set(ctx, "key1", "value1", 1, "default")

    // Get the value from the cache
    data, found, _ := c.Get(ctx, "key1")
    if found {
        fmt.Println("Found:", data)
    } else {
        fmt.Println("Not found")
    }

    // Delete the value from the cache
    c.Delete(ctx, "key1")

    // Try to get the value again after deletion
    data, found, _ = c.Get(ctx, "key1")
    if found {
        fmt.Println("Found:", data)
    } else {
        fmt.Println("Not found after deletion")
    }
}

Caching Maps

Easy-Cache supports caching map[string]interface{} natively:

package main

import (
    "context"
    "fmt"
    "github.com/onurbaran/easy-cache/pkg/cache"
)

func main() {
    // Create a MapCache
    config := cache.DefaultConfig()
    mapCache := cache.NewMapCache(config)

    // Cache a map
    ctx := context.Background()
    exampleMap := map[string]interface{}{"key1": "value1", "key2": "value2"}
    mapCache.Set(ctx, "example", exampleMap)

    // Retrieve the map from the cache
    data, found, err := mapCache.Get(ctx, "example")
    if err != nil {
        fmt.Println("Error getting map from cache:", err)
        return
    }
    if found {
        fmt.Printf("Found map in cache: %+v\n", data)
    } else {
        fmt.Println("Map not found in cache")
    }
}

Caching Slices

You can also cache []interface{} slices natively:

package main

import (
    "context"
    "fmt"
    "github.com/onurbaran/easy-cache/pkg/cache"
)

func main() {
    // Create a SliceCache
    config := cache.DefaultConfig()
    sliceCache := cache.NewSliceCache(config)

    // Cache a slice
    ctx := context.Background()
    exampleSlice := []interface{}{"value1", "value2", "value3"}
    sliceCache.Set(ctx, "exampleSlice", exampleSlice)

    // Retrieve the slice from the cache
    data, found, err := sliceCache.Get(ctx, "exampleSlice")
    if err != nil {
        fmt.Println("Error getting slice from cache:", err)
        return
    }
    if found {
        fmt.Printf("Found slice in cache: %+v\n", data)
    } else {
        fmt.Println("Slice not found in cache")
    }
}

Caching Structs with TTL

Structs can be cached with a TTL (Time-To-Live) to automatically expire after a certain period:

package main

import (
    "context"
    "fmt"
    "time"
    "github.com/onurbaran/easy-cache/pkg/cache"
)

type User struct {
    Name  string
    Email string
    Age   int
}

func main() {
    // Create a StructCache with a 5-second TTL
    config := cache.DefaultConfig()
    config.BaseTTL = 5 * time.Second
    structCache := cache.NewStructCache(config)

    // Cache a struct
    ctx := context.Background()
    user := User{Name: "Alice", Email: "alice@example.com", Age: 30}
    err := structCache.Set(ctx, "user1", user)
    if err != nil {
        fmt.Println("Error setting struct in cache:", err)
        return
    }

    // Retrieve the struct from the cache
    data, found, _ := structCache.Get(ctx, "user1")
    if found {
        fmt.Printf("Initially found struct in cache: %+v\n", data.(User))
    } else {
        fmt.Println("Struct not found in cache initially")
    }

    // Wait for the TTL to expire
    time.Sleep(6 * time.Second)

    // Check the cache after TTL expiration
    data, found, _ = structCache.Get(ctx, "user1")
    if !found {
        fmt.Println("Struct has expired and is no longer in cache")
    } else {
        fmt.Printf("Struct still found in cache after TTL: %+v\n", data.(User))
    }
}

Event-Driven Invalidation

Easy-Cache supports event-driven cache invalidation, allowing you to remove or update cache entries based on custom events.

package main

import (
    "context"
    "fmt"
    "github.com/onurbaran/easy-cache/pkg/cache"
    "github.com/onurbaran/easy-cache/pkg/event"
)

type User struct {
    Name  string
    Email string
    Age   int
}

type InvalidateEventListener struct {
    cache *cache.StructCache
}

func (l *InvalidateEventListener) OnEvent(e event.Event) {
    ctx := context.Background()
    key := e.Data.(string)
    l.cache.Delete(ctx, key)
    fmt.Println("Invalidated struct with key:", key)
}

func main() {
    // Create an Event Manager and attach it to the cache
    eventManager := event.NewEventManager()
    config := cache.DefaultConfig()
    config.EventManager = eventManager
    structCache := cache.NewStructCache(config)

    // Cache a struct
    ctx := context.Background()
    user := User{Name: "Alice", Email: "alice@example.com", Age: 30}
    structCache.Set(ctx, "user1", user)

    // Register an event listener
    listener := &InvalidateEventListener{cache: structCache}
    eventManager.RegisterListener("invalidateUser", listener)

    // Trigger the invalidation event
    eventManager.TriggerEvent(event.Event{Name: "invalidateUser", Data: "user1"})

    // Check the cache after event
    data, found, _ := structCache.Get(ctx, "user1")
    if !found {
        fmt.Println("Struct successfully invalidated and deleted from cache")
    } else {
        fmt.Println("Struct still found in cache:", data)
    }
}

Advanced Features

Eviction Policies

Easy-Cache supports LRU (Least Recently Used) and LFU (Least Frequently Used) eviction policies to manage cache size.

LRU Eviction

config := cache.DefaultConfig()
config.EvictionPolicy = &cache.LRUEviction{}

LFU Eviction

config := cache.DefaultConfig()
config.EvictionPolicy = &cache.LFUEviction{}

Sharded Cache

Easy-Cache allows you to shard your cache across multiple instances for improved scalability.

config := cache.DefaultConfig()
config.NumShards = 8
shardedCache := cache.NewShardedCache(config)

TODO

• Distributed cache
• Gossip Protocol Implementation
• Avro Serialization/Deserialization
• Adaptive TTL Management

Conclusion

Easy-Cache is a flexible caching library designed to handle various data structures efficiently in Go. With features like native caching, TTL, eviction policies, and event-driven invalidation, it provides a solution for caching in high-performance applications.

Feel free to explore the examples provided and integrate Easy-Cache into your Go projects. For more information, check out the source code and additional documentation.

License

This project is licensed under the MIT License.

---