xcache

README

XCache

WIP — work in progress

A type-safe, zero-config Go caching library with pluggable backends.

// One line to start
cache := xcache.New[User](memory.NewStore())

// Scale to Redis when needed
l1 := memory.NewStore(memory.WithShards(64))
l2 := redis.NewStore(redisClient)
userCache := xcache.New[User](xcache.NewChain(l1, l2))

// Cache stampede protection built-in
user, err := userCache.GetOrLoad(ctx, "user:123", func() (User, error) {
    return db.FindUserByID(123)
}, xcache.WithTTL(10*time.Minute))

Features

• Type-safe generics API — no type assertions, ever
• Zero-config — works in-memory with one line
• Pluggable backends — Memory, Redis, Memcached
• Chain cache — L1 (memory) → L2 (Redis) fallback
• Singleflight — prevents cache stampede on GetOrLoad
• Observability — Prometheus decorator

Testing

# Unit tests (verbose)
go test -v ./...

# With race detector
go test -v -race ./...

# Benchmarks (all cores: 1, 2, 4, 8)
# Linux / macOS
go test -bench=. -benchmem -cpu=1,2,4,8 ./...
# Windows (PowerShell)
go test --% -bench=. -benchmem -cpu=1,2,4,8 ./...

# Specific package
go test -v ./store/memory/...

Requirements

Go 1.21+

License

MIT

Documentation

Index

• Variables
• type Cache
  • func New[T any](store Store) Cache[T]
• type ChainStore
  • func NewChain(stores ...Store) *ChainStore
  • func (c *ChainStore) Clear(ctx context.Context) error
  • func (c *ChainStore) Close() error
  • func (c *ChainStore) Delete(ctx context.Context, key string) error
  • func (c *ChainStore) DeleteMany(ctx context.Context, keys []string) error
  • func (c *ChainStore) Get(ctx context.Context, key string) (any, error)
  • func (c *ChainStore) GetMany(ctx context.Context, keys []string) (map[string]any, error)
  • func (c *ChainStore) Set(ctx context.Context, key string, value any, opts ...Option) error
• type Option
  • func WithTTL(d time.Duration) Option
  • func WithTags(tags ...string) Option
• type Options
  • func ApplyOptions(opts []Option) *Options
• type Store

Variables

var ErrNotFound = errors.New("xcache: key not found")

ErrNotFound is returned when a key is not found or has expired.

Types

type Cache

type Cache[T any] interface {
	Get(ctx context.Context, key string) (T, error)
	Set(ctx context.Context, key string, value T, opts ...Option) error
	Delete(ctx context.Context, key string) error
	Clear(ctx context.Context) error
	GetOrLoad(ctx context.Context, key string, loader func(ctx context.Context) (T, error), opts ...Option) (T, error)
	GetMany(ctx context.Context, keys []string) (map[string]T, error)
	DeleteMany(ctx context.Context, keys []string) error
}

func New

func New[T any](store Store) Cache[T]

type ChainStore

type ChainStore struct {
	// contains filtered or unexported fields
}

ChainStore esegue le operazioni in cascata su una lista di Store (es. L1→L2). Get cerca nell'ordine: primo store che risponde vince. Set e Delete propagano a tutti gli store.

func NewChain

func NewChain(stores ...Store) *ChainStore

func (*ChainStore) Clear

func (c *ChainStore) Clear(ctx context.Context) error

func (*ChainStore) Close

func (c *ChainStore) Close() error

func (*ChainStore) Delete

func (c *ChainStore) Delete(ctx context.Context, key string) error

func (*ChainStore) DeleteMany

func (c *ChainStore) DeleteMany(ctx context.Context, keys []string) error

func (*ChainStore) Get

func (c *ChainStore) Get(ctx context.Context, key string) (any, error)

func (*ChainStore) GetMany

func (c *ChainStore) GetMany(ctx context.Context, keys []string) (map[string]any, error)

func (*ChainStore) Set

func (c *ChainStore) Set(ctx context.Context, key string, value any, opts ...Option) error

type Option

type Option func(*Options)

func WithTTL

func WithTTL(d time.Duration) Option

func WithTags

func WithTags(tags ...string) Option

type Options

type Options struct {
	TTL  time.Duration // 0 means no expiration
	Tags []string      // Invalidates all keys with any of these tags when deleted
}

func ApplyOptions

func ApplyOptions(opts []Option) *Options

applyOptions applies the given options and returns the resulting Options struct.

type Store

type Store interface {
	Get(ctx context.Context, key string) (any, error)
	Set(ctx context.Context, key string, value any, opts ...Option) error
	Delete(ctx context.Context, key string) error
	Clear(ctx context.Context) error
	Close() error
	GetMany(ctx context.Context, keys []string) (map[string]any, error)
	DeleteMany(ctx context.Context, keys []string) error
}