cache

type Cache[T any] interface {
	io.Closer

	// Get retrieves a value by key. Returns the value and true if found, zero value and false if not found.
	Get(ctx context.Context, key string) (T, bool)
	// GetOrLoad retrieves a value by key or computes it using the provided loader when missing.
	// Implementations must ensure concurrent calls for the same key only trigger a single loader execution.
	GetOrLoad(ctx context.Context, key string, loader LoaderFunc[T], ttl ...time.Duration) (T, error)
	// Set stores a value with the given key. If ttl is provided and > 0, the entry will expire after the duration.
	Set(ctx context.Context, key string, value T, ttl ...time.Duration) error
	// Contains checks if a key exists in the cache.
	Contains(ctx context.Context, key string) bool
	// Delete removes a key from the cache.
	Delete(ctx context.Context, key string) error
	// Clear removes all entries from the cache.
	Clear(ctx context.Context) error
	// Keys returns all keys in the cache, optionally filtered by prefix.
	Keys(ctx context.Context, prefix ...string) ([]string, error)
	// ForEach iterates over all key-value pairs in the cache, optionally filtered by prefix.
	// The iteration stops if the callback returns false.
	ForEach(ctx context.Context, callback func(key string, value T) bool, prefix ...string) error
	// Size returns the number of entries in the cache.
	Size(ctx context.Context) (int64, error)
}

type EvictionHandler interface {
	// OnAccess is called when an entry is accessed.
	OnAccess(key string)
	// OnInsert is called when a new entry is inserted.
	OnInsert(key string)
	// OnEvict is called when an entry is evicted.
	OnEvict(key string)
	// SelectEvictionCandidate selects a key to evict, returns empty string if no candidate.
	SelectEvictionCandidate() string
	// Reset clears all eviction tracking data.
	Reset()
}

type EvictionHandlerFactory struct{}

type EvictionPolicy int

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

type GetFunc[T any] func(context.Context, string) (T, bool)

type KeyBuilder interface {
	// Build constructs a cache key from the given base key
	Build(keyParts ...string) string
}

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

type LoaderFunc[T any] func(ctx context.Context) (T, error)

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

type MemoryOption func(*memoryConfig)

type NoOpEvictionHandler struct{}

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

type RedisOption func(*redisConfig)

type Serializer[T any] interface {
	// Serialize converts a value of type T into a byte array for storage
	Serialize(value T) ([]byte, error)
	// Deserialize converts a byte array back into a value of type T
	Deserialize(data []byte) (T, error)
}

type SetFunc[T any] func(context.Context, string, T, ...time.Duration) error

type SingleflightMixin[T any] struct {
	// contains filtered or unexported fields
}

type Store interface {
	// Name returns the name of the store.
	Name() string
	// Get retrieves raw bytes by key. Returns the data and true if found, nil and false if not found.
	Get(ctx context.Context, key string) ([]byte, bool)
	// Set stores raw bytes with the given key. If ttl is provided and > 0, the entry will expire after the duration.
	Set(ctx context.Context, key string, data []byte, ttl ...time.Duration) error
	// Contains checks if a key exists in the cache.
	Contains(ctx context.Context, key string) bool
	// Delete removes a key from the cache.
	Delete(ctx context.Context, key string) error
	// Clear removes all entries from the cache.
	Clear(ctx context.Context, prefix string) error
	// Keys returns all keys in the cache, optionally filtered by prefix.
	Keys(ctx context.Context, prefix string) ([]string, error)
	// ForEachRaw iterates over all key-value pairs in the cache, optionally filtered by prefix.
	// The iteration stops if the callback returns false.
	ForEach(ctx context.Context, prefix string, callback func(key string, data []byte) bool) error
	// Size returns the number of entries in the cache.
	Size(ctx context.Context, prefix string) (int64, error)
	// Close closes the cache and releases any resources.
	Close(ctx context.Context) error
}