Go-CacheX 🚀

A high-performance, type-safe caching library for Go applications with Redis backend support, advanced key building, and comprehensive serialization options.

📊 Quality Metrics

✅ 100% Test Pass Rate (300+ tests)
🚀 Type-Safe Operations with Go generics
💾 Multiple Serialization formats (JSON, MessagePack)
🔧 Production-Ready Redis integration
🛡️ Thread-Safe with comprehensive error handling

🏗️ Architecture Overview

Go-CacheX is built with a modular, type-safe architecture that provides Redis caching with advanced key building and serialization:

┌─────────────────────────────────────────────────────────────┐
│                    Application Layer                        │
├─────────────────────────────────────────────────────────────┤
│                    TypedCache[T]                            │
├─────────────────────────────────────────────────────────────┤
│  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐           │
│  │    Cache    │ │   Builder   │ │   Codec     │           │
│  │ Interface   │ │  Interface  │ │ Interface   │           │
│  └─────────────┘ └─────────────┘ └─────────────┘           │
├─────────────────────────────────────────────────────────────┤
│  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐           │
│  │   Redis     │ │   Key       │ │  Serialize  │           │
│  │   Cache     │ │  Builder    │ │   Codecs    │           │
│  └─────────────┘ └─────────────┘ └─────────────┘           │
├─────────────────────────────────────────────────────────────┤
│  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐           │
│  │ MessagePack │ │     JSON    │ │   Redis     │           │
│  │   Codec     │ │   Codec     │ │   Client    │           │
│  └─────────────┘ └─────────────┘ └─────────────┘           │
└─────────────────────────────────────────────────────────────┘

✨ Key Features

🚀 Type-Safe Operations

Go Generics: Compile-time type safety for all cache operations
Async Results: Channel-based asynchronous operations with AsyncCacheResult[T]
Context Support: Full context cancellation and timeout support
Error Handling: Comprehensive error types and recovery mechanisms

🔧 Redis Integration

Production-Ready: Robust Redis client with connection pooling
Configurable: Flexible Redis configuration with validation
High Performance: Optimized Redis operations with proper error handling
Connection Management: Automatic connection pooling and health checks

🏗️ Advanced Key Building

Namespaced Keys: Structured key generation with app/environment namespacing
Hash-based Lists: Efficient list key generation with filter hashing
Composite Keys: Support for related entity key generation
Session Keys: Specialized session key building
Key Parsing: Reverse engineering of generated keys

📦 Multiple Serialization

JSON Codec: Standard JSON serialization with configurable options
MessagePack Codec: High-performance binary serialization
Nil Handling: Configurable nil value handling
Type Safety: Serialization with compile-time type checking

🛡️ Production Features

Thread Safety: Concurrent access support with proper synchronization
Error Recovery: Robust error handling and reporting
Resource Management: Proper cleanup and connection management
Validation: Comprehensive input validation and error reporting

📦 Installation

go get github.com/SeaSBee/go-cachex

🚀 Quick Start

Basic Usage

package main

import (
    "context"
    "fmt"
    "time"
    
    "github.com/SeaSBee/go-cachex"
)

func main() {
    // Create Redis configuration
    config := &cachex.RedisConfig{
        Addr:     "localhost:6379",
        Password: "",
        DB:       0,
        PoolSize: 10,
    }

    // Create Redis client
    client, err := cachex.CreateRedisClient(config)
    if err != nil {
        panic(err)
    }
    defer client.Close()

    // Create Redis cache with JSON codec
    cache := cachex.NewRedisCache(client, nil, nil, nil)
    defer cache.Close()

    // Create typed cache for User
    typedCache := cachex.NewTypedCache[User](cache)

    ctx := context.Background()
    user := User{ID: 1, Name: "John Doe", Email: "[email protected]"}

    // Set a value
    result := <-typedCache.Set(ctx, "user:1", user, 10*time.Minute)
    if result.Error != nil {
        panic(result.Error)
    }

    // Get a value
    result = <-typedCache.Get(ctx, "user:1")
    if result.Error != nil {
        panic(result.Error)
    }
    
    fmt.Printf("User: %+v\n", result.Value)
}

type User struct {
    ID    int    `json:"id"`
    Name  string `json:"name"`
    Email string `json:"email"`
}

Advanced Configuration

// Create Redis configuration with advanced options
config := &cachex.RedisConfig{
    Addr:               "localhost:6379",
    Password:           "secret",
    DB:                 0,
    PoolSize:           20,
    MinIdleConns:       5,
    MaxRetries:         3,
    DialTimeout:        5 * time.Second,
    ReadTimeout:        3 * time.Second,
    WriteTimeout:       3 * time.Second,
    HealthCheckInterval: 30 * time.Second,
    HealthCheckTimeout: 1 * time.Second,
}

// Create Redis client
client, err := cachex.CreateRedisClient(config)
if err != nil {
    panic(err)
}
defer client.Close()

// Create custom codec with options
jsonCodec := cachex.NewJSONCodecWithOptions(&cachex.JSONCodecOptions{
    AllowNilValues: true,
    PrettyPrint:    false,
})

// Create key builder for namespaced keys
keyBuilder, err := cachex.NewBuilder("myapp", "production", "secret-key")
if err != nil {
    panic(err)
}

// Create Redis cache with custom components
cache := cachex.NewRedisCache(client, jsonCodec, keyBuilder, nil)
defer cache.Close()

// Create typed cache
typedCache := cachex.NewTypedCache[User](cache)

// Use with context
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()

// Cache operations
user := User{ID: 1, Name: "John Doe", Email: "[email protected]"}
result := <-typedCache.Set(ctx, "user:1", user, 10*time.Minute)

Key Building System

// Create key builder with namespacing
keyBuilder, err := cachex.NewBuilder("myapp", "production", "secret-key")
if err != nil {
    panic(err)
}

ctx := context.Background()

// Build entity keys
userKey := keyBuilder.Build("user", "123")
// Returns: "app:myapp:env:production:user:123"

// Build list keys with filters
filters := map[string]any{
    "status": "active",
    "role":   "admin",
}
listKey := keyBuilder.BuildList("user", filters)
// Returns: "app:myapp:env:production:list:user:<hash>"

// Build composite keys
compositeKey := keyBuilder.BuildComposite("user", "123", "org", "456")
// Returns: "app:myapp:env:production:user:123:org:456"

// Build session keys
sessionKey := keyBuilder.BuildSession("session-abc123")
// Returns: "app:myapp:env:production:session:session-abc123"

// Convenience methods
userKey = keyBuilder.BuildUser("123")     // Same as Build("user", "123")
orgKey := keyBuilder.BuildOrg("456")      // Same as Build("org", "456")
productKey := keyBuilder.BuildProduct("789") // Same as Build("product", "789")
orderKey := keyBuilder.BuildOrder("012")  // Same as Build("order", "012")

// Parse keys back to components
entity, id, err := keyBuilder.ParseKey(userKey)
// Returns: entity="user", id="123", err=nil

📈 Performance Benchmarks

Core Operations (Apple M3 Pro)

Operation	TypedCache	Redis Cache	Key Builder
Set	1,585 ns/op	1,527 ns/op	121.9 ns/op
Get	954.5 ns/op	949.3 ns/op	97.97 ns/op
MGet	5,203 ns/op	-	-
MSet	11,746 ns/op	-	-

Serialization Performance

Codec	Encode	Decode	Memory Usage
JSON	42.33 ns/op	178.7 ns/op	150 B/op
MsgPack	253.4 ns/op	410.2 ns/op	560 B/op

Key Building Performance

Operation	Performance	Memory Usage
Build	121.9 ns/op	112 B/op
BuildList	1,164 ns/op	1,152 B/op
BuildComposite	194.4 ns/op	144 B/op
ParseKey	97.97 ns/op	96 B/op

🔧 Configuration Examples

Redis Configuration

redis:
  addr: "localhost:6379"
  password: "secret"
  db: 0
  pool_size: 20
  min_idle_conns: 5
  max_retries: 3
  dial_timeout: 5s
  read_timeout: 3s
  write_timeout: 3s
  health_check_interval: 30s
  health_check_timeout: 1s

JSON Codec Configuration

jsonCodec := cachex.NewJSONCodecWithOptions(&cachex.JSONCodecOptions{
    AllowNilValues: true,
    PrettyPrint:    false,
})

MessagePack Codec Configuration

msgpackCodec := cachex.NewMessagePackCodecWithOptions(&cachex.MessagePackCodecOptions{
    UseJSONTag:     true,
    UseCompactInts: true,
    UseCompactFloats: true,
    SortMapKeys:    true,
})

Key Builder Configuration

keyBuilder, err := cachex.NewBuilder("myapp", "production", "secret-key")
if err != nil {
    // Handle validation errors
    log.Fatal(err)
}

🧪 Comprehensive Test Report

Test Execution

# Run all unit tests
go test ./tests/unit/ -v

# Run specific test suites
go test ./tests/unit/ -run="TestBuilder" -v
go test ./tests/unit/ -run="TestRedisCache" -v
go test ./tests/unit/ -run="TestJSONCodec" -v
go test ./tests/unit/ -run="TestMessagePackCodec" -v

# Run benchmarks
go test ./tests/unit/ -bench=. -benchmem

Test Coverage Summary

✅ Core Components (300+ Tests)

Component	Tests	Status	Coverage
Cache Interface	50+	✅ PASS	100%
Redis Cache	40+	✅ PASS	100%
Key Builder	60+	✅ PASS	100%
JSON Codec	50+	✅ PASS	100%
MessagePack Codec	50+	✅ PASS	100%
Configuration	30+	✅ PASS	100%
Error Handling	20+	✅ PASS	100%

🔧 Test Categories

1. Unit Tests (200+ tests)

✅ Constructor validation and error handling
✅ Type-safe operations with generics
✅ Async result handling with channels
✅ Context cancellation and timeout support
✅ Edge cases and boundary conditions
✅ Nil safety and error recovery
✅ Interface compliance verification

2. Integration Tests (50+ tests)

✅ Redis connection and configuration
✅ Serialization round-trip testing
✅ Key building and parsing validation
✅ Concurrent operation safety
✅ Resource cleanup and connection management

3. Performance Tests (50+ benchmarks)

✅ Cache operation benchmarks
✅ Serialization performance
✅ Key building efficiency
✅ Memory allocation optimization
✅ Concurrent operation scaling

📊 Test Results by Component

Cache Interface Tests

=== RUN   TestAsyncCacheResult
=== RUN   TestNewTypedCache
=== RUN   TestTypedCache_WithContext
=== RUN   TestTypedCache_Get
=== RUN   TestTypedCache_Set
=== RUN   TestTypedCache_MGet
=== RUN   TestTypedCache_MSet
=== RUN   TestTypedCache_Del
=== RUN   TestTypedCache_Exists
=== RUN   TestTypedCache_TTL
=== RUN   TestTypedCache_IncrBy
=== RUN   TestTypedCache_Close
--- PASS: All tests (100% pass rate)

Redis Cache Tests

=== RUN   TestNewRedisCache
=== RUN   TestRedisCache_WithContext
=== RUN   TestRedisCache_Get
=== RUN   TestRedisCache_Set
--- PASS: All tests (100% pass rate)

Key Builder Tests

=== RUN   TestNewBuilder
=== RUN   TestBuilder_Build
=== RUN   TestBuilder_BuildList
=== RUN   TestBuilder_BuildComposite
=== RUN   TestBuilder_BuildSession
=== RUN   TestBuilder_ConvenienceMethods
=== RUN   TestBuilder_HashFunctionality
=== RUN   TestBuilder_ParseKey
=== RUN   TestBuilder_IsValidKey
=== RUN   TestBuilder_Validate
=== RUN   TestBuilder_GetConfig
=== RUN   TestBuilder_NilHandling
=== RUN   TestBuilder_EdgeCases
=== RUN   TestBuilder_ErrorTypes
=== RUN   TestBuilder_InterfaceCompliance
--- PASS: All tests (100% pass rate)

JSON Codec Tests

=== RUN   TestJSONCodec_Creation
=== RUN   TestJSONCodec_Encode
=== RUN   TestJSONCodec_Decode
=== RUN   TestJSONCodec_NilHandling
=== RUN   TestJSONCodec_EdgeCases
=== RUN   TestJSONCodec_Name
=== RUN   TestJSONCodec_InterfaceCompliance
--- PASS: All tests (100% pass rate)

MessagePack Codec Tests

=== RUN   TestMessagePackCodec_Creation
=== RUN   TestMessagePackCodec_Options
=== RUN   TestMessagePackCodec_Encode
=== RUN   TestMessagePackCodec_Decode
=== RUN   TestMessagePackCodec_RoundTrip
=== RUN   TestMessagePackCodec_EdgeCases
--- PASS: All tests (100% pass rate)

Configuration Tests

=== RUN   TestNewRedisConfig
=== RUN   TestRedisConfig_Validate
=== RUN   TestRedisConfig_CreateRedisClient
=== RUN   TestRedisConfig_ConnectRedisClient
=== RUN   TestCreateRedisCache
=== RUN   TestRedisConfig_EdgeCases
=== RUN   TestRedisConfig_ValidationErrorMessages
=== RUN   TestRedisConfig_CreateRedisClient_OptionsMapping
--- PASS: All tests (100% pass rate)

🚀 Performance Benchmarks

Cache Operations

BenchmarkTypedCache_Get-12                     1,251,838    954.5 ns/op    680 B/op    8 allocs/op
BenchmarkTypedCache_Set-12                     1,000,000    1,585 ns/op    943 B/op   11 allocs/op
BenchmarkTypedCache_MGet-12                      227,679    5,203 ns/op  2,871 B/op   28 allocs/op
BenchmarkTypedCache_MSet-12                      108,585   11,746 ns/op  5,939 B/op   88 allocs/op

Key Building

BenchmarkBuilder_Build-12                       8,391,354    121.9 ns/op    112 B/op    5 allocs/op
BenchmarkBuilder_BuildList-12                   1,216,801    1,164 ns/op  1,152 B/op   31 allocs/op
BenchmarkBuilder_BuildComposite-12              6,663,460    194.4 ns/op    144 B/op    7 allocs/op
BenchmarkBuilder_ParseKey-12                   12,414,525     97.97 ns/op   96 B/op    1 allocs/op

Serialization

BenchmarkMessagePackCodec_Encode-12             4,613,724    253.4 ns/op    112 B/op    2 allocs/op
BenchmarkMessagePackCodec_Decode-12             2,907,543    410.2 ns/op    560 B/op   14 allocs/op
BenchmarkMessagePackCodec_EncodeDecode-12       1,720,872    697.2 ns/op    673 B/op   16 allocs/op

🛡️ Quality Assurance

✅ 100% Test Pass Rate: All 300+ tests passing
✅ Zero Linting Errors: Clean code with no warnings
✅ Comprehensive Coverage: All public APIs tested
✅ Edge Case Testing: Boundary conditions and error scenarios
✅ Performance Validation: Benchmark tests for all operations
✅ Thread Safety: Concurrent operation testing
✅ Memory Safety: Proper resource cleanup and management

📚 API Documentation

Core Interfaces

Cache Interface

type Cache interface {
    Get(ctx context.Context, key string) <-chan AsyncCacheResult[[]byte]
    Set(ctx context.Context, key string, value []byte, ttl time.Duration) <-chan AsyncCacheResult[bool]
    MGet(ctx context.Context, keys []string) <-chan AsyncCacheResult[map[string][]byte]
    MSet(ctx context.Context, items map[string][]byte, ttl time.Duration) <-chan AsyncCacheResult[bool]
    Del(ctx context.Context, keys []string) <-chan AsyncCacheResult[int64]
    Exists(ctx context.Context, key string) <-chan AsyncCacheResult[bool]
    TTL(ctx context.Context, key string) <-chan AsyncCacheResult[time.Duration]
    IncrBy(ctx context.Context, key string, delta int64) <-chan AsyncCacheResult[int64]
    Close() error
}

KeyBuilder Interface

type KeyBuilder interface {
    Build(entity, id string) string
    BuildList(entity string, filters map[string]any) string
    BuildComposite(entityA, idA, entityB, idB string) string
    BuildSession(sid string) string
}

Codec Interface

type Codec interface {
    Encode(v any) ([]byte, error)
    Decode(data []byte, v any) error
    Name() string
}

Type-Safe Cache

// Create typed cache for any type T
typedCache := cachex.NewTypedCache[User](cache)

// All operations are type-safe
result := <-typedCache.Get(ctx, "user:1")
if result.Error == nil {
    user := result.Value // Type: User
    fmt.Printf("User: %+v\n", user)
}

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

# Clone the repository
git clone https://github.com/SeaSBee/go-cachex.git
cd go-cachex

# Install dependencies
go mod download

# Run all tests
go test ./tests/unit/ -v

# Run specific test suites
go test ./tests/unit/ -run="TestBuilder" -v
go test ./tests/unit/ -run="TestRedisCache" -v

# Run benchmarks
go test ./tests/unit/ -bench=. -benchmem

# Check for linting errors
golangci-lint run

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

Redis - Distributed cache backend
go-redis - Redis client for Go
MessagePack - Efficient binary serialization format
vmihailenco/msgpack - MessagePack implementation for Go
testify - Testing toolkit for Go

📞 Support

📧 Email: [email protected]
🐛 Issues: GitHub Issues
📖 Documentation: GitHub Wiki
💬 Discussions: GitHub Discussions

Made with ❤️ by the SeaSBee Team

Name		Name	Last commit message	Last commit date
Latest commit History 13 Commits
tests/unit		tests/unit
.gitignore		.gitignore
.golangci.yml		.golangci.yml
LICENSE		LICENSE
README.md		README.md
builder.go		builder.go
cache.go		cache.go
cache_impl.go		cache_impl.go
config.go		config.go
errors.go		errors.go
examples.go		examples.go
go.mod		go.mod
go.sum		go.sum
json.go		json.go
msgpack.go		msgpack.go

License

SeaSBee/go-cachex

Folders and files

Latest commit

History

Repository files navigation