cache

package module
v1.0.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jan 26, 2026 License: Apache-2.0 Imports: 10 Imported by: 0

README

cache-kit

A Go library for thread-safe, multi-index memory caching with Redis support.

Features

  • Multi-Index Lookup: O(1) lookups by multiple keys (e.g., ID, email, phone)
  • Thread-Safe: Safe for concurrent read/write access
  • Hash-Based Change Detection: Detect cache changes efficiently
  • Redis Support: Redis cache adapter for distributed scenarios
  • Hybrid Cache: Combine memory and Redis for optimal performance
  • Generic Types: Works with any data type using Go generics
  • Fluent Configuration: Builder pattern for easy configuration

Installation

go get github.com/soulteary/cache-kit

Quick Start

Memory Cache with Multi-Index
package main

import (
    "fmt"
    cache "github.com/soulteary/cache-kit"
)

type User struct {
    ID    string
    Email string
    Phone string
    Name  string
}

func main() {
    // Create cache with primary key
    config := cache.DefaultConfig[User]().
        WithPrimaryKey(func(u User) string { return u.ID })

    c := cache.NewMultiIndexCache(config)

    // Add indexes for fast lookup by email and phone
    c.AddIndex("email", func(u User) string { return u.Email })
    c.AddIndex("phone", func(u User) string { return u.Phone })

    // Set data
    users := []User{
        {ID: "1", Email: "alice@example.com", Phone: "1111111111", Name: "Alice"},
        {ID: "2", Email: "bob@example.com", Phone: "2222222222", Name: "Bob"},
    }
    c.Set(users)

    // Lookup by primary key (O(1))
    user, ok := c.Get("1")
    if ok {
        fmt.Println("Found by ID:", user.Name)
    }

    // Lookup by email index (O(1))
    user, ok = c.GetByIndex("email", "bob@example.com")
    if ok {
        fmt.Println("Found by email:", user.Name)
    }

    // Lookup by phone index (O(1))
    user, ok = c.GetByIndex("phone", "1111111111")
    if ok {
        fmt.Println("Found by phone:", user.Name)
    }

    // Get hash for change detection
    fmt.Println("Cache hash:", c.GetHash())
}
Redis Cache
package main

import (
    "github.com/redis/go-redis/v9"
    cache "github.com/soulteary/cache-kit"
)

func main() {
    client := redis.NewClient(&redis.Options{
        Addr: "localhost:6379",
    })
    defer client.Close()

    // Create Redis cache
    config := cache.DefaultRedisConfig().
        WithKeyPrefix("myapp:users:").
        WithTTL(30 * time.Minute)

    c := cache.NewRedisCache[User](client, config)

    // Set data
    users := []User{{ID: "1", Name: "Alice"}}
    if err := c.Set(users); err != nil {
        panic(err)
    }

    // Get data
    users, err := c.Get()
    if err != nil {
        panic(err)
    }

    // Check version (for cache invalidation)
    version, _ := c.GetVersion()
    fmt.Println("Cache version:", version)
}
Hybrid Cache (Memory + Redis)
package main

import (
    "github.com/redis/go-redis/v9"
    cache "github.com/soulteary/cache-kit"
)

func main() {
    client := redis.NewClient(&redis.Options{
        Addr: "localhost:6379",
    })
    defer client.Close()

    // Create hybrid cache
    memConfig := cache.DefaultConfig[User]().
        WithPrimaryKey(func(u User) string { return u.ID })
    redisConfig := cache.DefaultRedisConfig().WithKeyPrefix("users:")

    c := cache.NewHybridCache[User](memConfig, client, redisConfig)

    // Add indexes
    c.AddIndex("email", func(u User) string { return u.Email })

    // Set stores in both memory and Redis
    c.Set([]User{{ID: "1", Email: "alice@example.com"}})

    // Fast lookup from memory
    user, ok := c.GetByIndex("email", "alice@example.com")

    // Load from Redis on startup
    c.LoadFromRedis()

    // Sync memory to Redis
    c.SyncToRedis()
}

Configuration

Memory Cache Config
config := cache.DefaultConfig[User]().
    // Required: Primary key extraction
    WithPrimaryKey(func(u User) string { return u.ID }).

    // Optional: Custom hash function
    WithHashFunc(func(users []User) string {
        // Your custom hash logic
        return "custom-hash"
    }).

    // Optional: Validation (skip invalid items)
    WithValidateFunc(func(u User) error {
        if u.ID == "" {
            return fmt.Errorf("ID required")
        }
        return nil
    }).

    // Optional: Normalization (transform before storing)
    WithNormalizeFunc(func(u User) User {
        u.Email = strings.ToLower(u.Email)
        return u
    }).

    // Optional: Sort function for deterministic hashing
    WithSortFunc(cache.StringSorter(func(u User) string {
        return u.ID
    }))
Redis Config
config := cache.DefaultRedisConfig().
    WithKeyPrefix("myapp:cache:").    // Key prefix
    WithVersionKeySuffix(":version"). // Version key suffix
    WithTTL(1 * time.Hour).           // Cache TTL
    WithOperationTimeout(5 * time.Second) // Operation timeout

API Reference

MemoryCache
// Create cache
cache := NewMultiIndexCache[V](config)

// Index management
cache.AddIndex(name, keyFunc)
cache.RemoveIndex(name)
cache.HasIndex(name) bool
cache.IndexCount() int
cache.IndexNames() []string

// Data operations
cache.Set(values)
cache.Get(primaryKey) (V, bool)
cache.GetByIndex(indexName, key) (V, bool)
cache.GetAll() []V
cache.Len() int
cache.Clear()

// Iteration
cache.Iterate(func(v V) bool)

// Change detection
cache.GetHash() string
RedisCache
// Create cache
cache := NewRedisCache[V](client, config)
cache := NewRedisCacheWithKey[V](client, "custom:key", config)

// Data operations
cache.Set(values) error
cache.SetWithTTL(values, ttl) error
cache.Get() ([]V, error)
cache.Clear() error

// Status
cache.Exists() (bool, error)
cache.GetVersion() (int64, error)
cache.TTL() (time.Duration, error)
cache.Refresh() error
HybridCache
// Create cache
cache := NewHybridCache[V](memConfig, redisClient, redisConfig)

// Index management
cache.AddIndex(name, keyFunc)

// Data operations
cache.Set(values) error
cache.GetByIndex(indexName, key) (V, bool)
cache.GetAll() []V

// Sync operations
cache.LoadFromRedis() error
cache.SyncToRedis() error

// Access underlying caches
cache.Memory() *MemoryCache[V]
cache.Redis() *RedisCache[V]

Use Cases

  • User whitelist caching: Fast O(1) lookups by phone, email, or user ID
  • Configuration caching: Cache config with multi-key access
  • Hot data caching: Frequently accessed data with multiple indexes
  • Distributed caching: Share cache across instances with Redis

License

Apache License 2.0

Documentation

Overview

Package cache provides multi-index memory cache with Redis support.

This package offers a generic, thread-safe caching solution with the following features:

  • Multi-index lookup support (O(1) lookups by different keys)
  • Hash-based change detection
  • Redis cache adapter for distributed scenarios
  • Automatic TTL management

Example usage: 

// Create a memory cache for users
cache := cache.NewMultiIndexCache[User](cache.DefaultConfig())

// Add indexes
cache.AddIndex("email", func(u User) string { return u.Email })
cache.AddIndex("user_id", func(u User) string { return u.UserID })

// Set items
cache.Set(users)

// Lookup by different keys
user, ok := cache.GetByIndex("email", "user@example.com")

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func StringSorter 

func StringSorter[V any](keyFunc func(V) string) func([]V) []V

StringSorter provides a helper for sorting slices by a string key.

Types

type Cache 

type Cache[K comparable, V any] interface {
	// Get retrieves a value by its primary key.
	Get(key K) (V, bool)

	// Set stores a value with its primary key.
	Set(key K, value V)

	// Delete removes a value by its primary key.
	Delete(key K)

	// GetAll returns all cached values.
	GetAll() []V

	// Len returns the number of cached items.
	Len() int

	// Clear removes all items from the cache.
	Clear()

	// GetHash returns a hash representing the current cache state.
	// Useful for detecting changes.
	GetHash() string
}

Cache provides the basic cache interface.

type Config 

type Config[V any] struct {
	// PrimaryKeyFunc extracts the primary key from a value.
	// This is required for multi-index cache.
	PrimaryKeyFunc KeyFunc[V]

	// HashFunc computes a hash for the cache contents.
	// If nil, a default hash function is used.
	HashFunc HashFunc[V]

	// ValidateFunc validates a value before storing.
	// If nil, all values are accepted.
	ValidateFunc ValidateFunc[V]

	// NormalizeFunc normalizes a value before storing.
	// If nil, values are stored as-is.
	NormalizeFunc NormalizeFunc[V]

	// SortFunc is used for deterministic hash calculation.
	// If nil, values are hashed in insertion order.
	SortFunc func(values []V) []V
}

Config holds configuration for the cache.

func DefaultConfig 

func DefaultConfig[V any]() *Config[V]

DefaultConfig returns a default configuration. Note: PrimaryKeyFunc must be set before use with MultiIndexCache.

func (*Config[V]) WithHashFunc 

func (c *Config[V]) WithHashFunc(fn HashFunc[V]) *Config[V]

WithHashFunc sets a custom hash function.

func (*Config[V]) WithNormalizeFunc 

func (c *Config[V]) WithNormalizeFunc(fn NormalizeFunc[V]) *Config[V]

WithNormalizeFunc sets a normalization function.

func (*Config[V]) WithPrimaryKey 

func (c *Config[V]) WithPrimaryKey(fn KeyFunc[V]) *Config[V]

WithPrimaryKey sets the primary key extraction function.

func (*Config[V]) WithSortFunc 

func (c *Config[V]) WithSortFunc(fn func(values []V) []V) *Config[V]

WithSortFunc sets a sort function for deterministic hashing.

func (*Config[V]) WithValidateFunc 

func (c *Config[V]) WithValidateFunc(fn ValidateFunc[V]) *Config[V]

WithValidateFunc sets a validation function.

type HashFunc 

type HashFunc[V any] func(values []V) string

HashFunc defines a function that computes a hash for a value.

type HybridCache 

type HybridCache[V any] struct {
	// contains filtered or unexported fields
}

HybridCache combines memory cache with Redis for distributed scenarios. It uses memory cache for fast local access and Redis for persistence/sharing.

func NewHybridCache 

func NewHybridCache[V any](memoryConfig *Config[V], redisClient *redis.Client, redisConfig *RedisConfig) *HybridCache[V]

NewHybridCache creates a new hybrid cache.

func (*HybridCache[V]) AddIndex 

func (c *HybridCache[V]) AddIndex(name string, keyFunc KeyFunc[V])

AddIndex registers a new index on the memory cache.

func (*HybridCache[V]) GetAll 

func (c *HybridCache[V]) GetAll() []V

GetAll returns all values from memory cache.

func (*HybridCache[V]) GetByIndex 

func (c *HybridCache[V]) GetByIndex(indexName string, key string) (V, bool)

GetByIndex retrieves a value from memory cache by index.

func (*HybridCache[V]) LoadFromRedis 

func (c *HybridCache[V]) LoadFromRedis() error

LoadFromRedis loads data from Redis into memory cache.

func (*HybridCache[V]) Memory 

func (c *HybridCache[V]) Memory() *MemoryCache[V]

Memory returns the underlying memory cache for direct access.

func (*HybridCache[V]) Redis 

func (c *HybridCache[V]) Redis() *RedisCache[V]

Redis returns the underlying Redis cache for direct access.

func (*HybridCache[V]) Set 

func (c *HybridCache[V]) Set(values []V) error

Set stores values in both memory and Redis.

func (*HybridCache[V]) SyncToRedis 

func (c *HybridCache[V]) SyncToRedis() error

SyncToRedis saves memory cache data to Redis.

type KeyFunc 

type KeyFunc[V any] func(value V) string

KeyFunc defines a function that extracts a key from a value.

type MemoryCache 

type MemoryCache[V any] struct {
	// contains filtered or unexported fields
}

MemoryCache provides a thread-safe, multi-index memory cache.

It supports O(1) lookups by primary key and by any registered index. The cache maintains insertion order and provides hash-based change detection.

func NewMultiIndexCache 

func NewMultiIndexCache[V any](config *Config[V]) *MemoryCache[V]

NewMultiIndexCache creates a new multi-index memory cache. The config must have a PrimaryKeyFunc set.

func (*MemoryCache[V]) AddIndex 

func (c *MemoryCache[V]) AddIndex(name string, keyFunc KeyFunc[V])

AddIndex registers a new index with a key extraction function. The keyFunc extracts the index key from a value. If an index with the same name exists, it will be replaced.

func (*MemoryCache[V]) Clear 

func (c *MemoryCache[V]) Clear()

Clear removes all items from the cache.

func (*MemoryCache[V]) Get 

func (c *MemoryCache[V]) Get(key string) (V, bool)

Get retrieves a value by its primary key.

func (*MemoryCache[V]) GetAll 

func (c *MemoryCache[V]) GetAll() []V

GetAll returns all cached values in insertion order.

func (*MemoryCache[V]) GetByIndex 

func (c *MemoryCache[V]) GetByIndex(indexName string, key string) (V, bool)

GetByIndex retrieves a value by a named index. Returns the value and true if found, zero value and false otherwise.

func (*MemoryCache[V]) GetHash 

func (c *MemoryCache[V]) GetHash() string

GetHash returns a hash representing the current cache state.

func (*MemoryCache[V]) HasIndex 

func (c *MemoryCache[V]) HasIndex(name string) bool

HasIndex checks if an index exists.

func (*MemoryCache[V]) IndexCount 

func (c *MemoryCache[V]) IndexCount() int

IndexCount returns the number of registered indexes.

func (*MemoryCache[V]) IndexNames 

func (c *MemoryCache[V]) IndexNames() []string

IndexNames returns the names of all registered indexes.

func (*MemoryCache[V]) Iterate 

func (c *MemoryCache[V]) Iterate(fn func(value V) bool)

Iterate applies a function to each cached value in insertion order. If the function returns false, iteration stops.

func (*MemoryCache[V]) Len 

func (c *MemoryCache[V]) Len() int

Len returns the number of cached items.

func (*MemoryCache[V]) RemoveIndex 

func (c *MemoryCache[V]) RemoveIndex(name string)

RemoveIndex removes an index by name.

func (*MemoryCache[V]) Set 

func (c *MemoryCache[V]) Set(values []V)

Set stores all values and rebuilds all indexes. Values are validated and normalized if the corresponding functions are set. Duplicate primary keys will be updated (last one wins).

type MultiIndexCache 

type MultiIndexCache[V any] interface {
	// GetByIndex retrieves a value by a named index.
	// Returns the value and true if found, zero value and false otherwise.
	GetByIndex(indexName string, key string) (V, bool)

	// AddIndex registers a new index with a key extraction function.
	// The keyFunc extracts the index key from a value.
	AddIndex(name string, keyFunc func(V) string)

	// RemoveIndex removes an index by name.
	RemoveIndex(name string)

	// HasIndex checks if an index exists.
	HasIndex(name string) bool

	// Set stores all values and rebuilds all indexes.
	Set(values []V)

	// GetAll returns all cached values in insertion order.
	GetAll() []V

	// Len returns the number of cached items.
	Len() int

	// Clear removes all items from the cache.
	Clear()

	// GetHash returns a hash representing the current cache state.
	GetHash() string

	// Iterate applies a function to each cached value.
	// If the function returns false, iteration stops.
	Iterate(fn func(value V) bool)
}

MultiIndexCache extends Cache with multi-index lookup capabilities.

type NormalizeFunc 

type NormalizeFunc[V any] func(value V) V

NormalizeFunc defines a function that normalizes a value. Returns the normalized value.

type RedisCache 

type RedisCache[V any] struct {
	// contains filtered or unexported fields
}

RedisCache provides a Redis-based cache implementation. It supports versioning for cache invalidation detection.

func NewRedisCache 

func NewRedisCache[V any](client *redis.Client, config *RedisConfig) *RedisCache[V]

NewRedisCache creates a new Redis cache with the given client and configuration.

func NewRedisCacheWithKey 

func NewRedisCacheWithKey[V any](client *redis.Client, key string, config *RedisConfig) *RedisCache[V]

NewRedisCacheWithKey creates a new Redis cache with a custom key name.

func (*RedisCache[V]) Clear 

func (c *RedisCache[V]) Clear() error

Clear deletes the cache key.

func (*RedisCache[V]) Exists 

func (c *RedisCache[V]) Exists() (bool, error)

Exists checks if the cache key exists.

func (*RedisCache[V]) Get 

func (c *RedisCache[V]) Get() ([]V, error)

Get retrieves values from Redis. Returns an empty slice if the key doesn't exist.

func (*RedisCache[V]) GetVersion 

func (c *RedisCache[V]) GetVersion() (int64, error)

GetVersion returns the current cache version. Returns 0 if the version key doesn't exist.

func (*RedisCache[V]) Refresh 

func (c *RedisCache[V]) Refresh() error

Refresh extends the TTL of the cache without changing the data.

func (*RedisCache[V]) Set 

func (c *RedisCache[V]) Set(values []V) error

Set stores values in Redis and increments the version.

func (*RedisCache[V]) SetWithTTL 

func (c *RedisCache[V]) SetWithTTL(values []V, ttl time.Duration) error

SetWithTTL stores values with a custom TTL.

func (*RedisCache[V]) TTL 

func (c *RedisCache[V]) TTL() (time.Duration, error)

TTL returns the remaining TTL for the cache key.

type RedisConfig 

type RedisConfig struct {
	// KeyPrefix is prepended to all Redis keys.
	KeyPrefix string

	// VersionKeySuffix is appended to the key prefix for version tracking.
	// Default: ":version"
	VersionKeySuffix string

	// TTL is the default time-to-live for cached data.
	// Default: 1 hour
	TTL time.Duration

	// OperationTimeout is the timeout for Redis operations.
	// Default: 5 seconds
	OperationTimeout time.Duration
}

RedisConfig holds configuration for Redis cache.

func DefaultRedisConfig 

func DefaultRedisConfig() *RedisConfig

DefaultRedisConfig returns a default Redis configuration.

func (*RedisConfig) WithKeyPrefix 

func (c *RedisConfig) WithKeyPrefix(prefix string) *RedisConfig

WithKeyPrefix sets the key prefix.

func (*RedisConfig) WithOperationTimeout 

func (c *RedisConfig) WithOperationTimeout(timeout time.Duration) *RedisConfig

WithOperationTimeout sets the operation timeout.

func (*RedisConfig) WithTTL 

func (c *RedisConfig) WithTTL(ttl time.Duration) *RedisConfig

WithTTL sets the TTL.

func (*RedisConfig) WithVersionKeySuffix 

func (c *RedisConfig) WithVersionKeySuffix(suffix string) *RedisConfig

WithVersionKeySuffix sets the version key suffix.

type ValidateFunc 

type ValidateFunc[V any] func(value V) error

ValidateFunc defines a function that validates a value. Returns an error if the value is invalid.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.