stash

README

stash

Replaces patrickmn/go-cache — type-safe in-memory cache with generics, eviction policies, and sharded concurrency (7,109 importers, unmaintained since 2017)

Documentation

Overview

Package stash provides a type-safe, generics-based in-memory cache with TTL expiration, eviction policies, and sharded concurrency support. It is a drop-in replacement for patrickmn/go-cache.

Index

• Constants
• Variables
• type Cache
  • func New[K comparable, V any](opts ...Option[K, V]) *Cache[K, V]
  • func (c *Cache[K, V]) Add(key K, val V, ttl time.Duration) error
  • func (c *Cache[K, V]) Count() int
  • func (c *Cache[K, V]) Delete(key K)
  • func (c *Cache[K, V]) DeleteExpired()
  • func (c *Cache[K, V]) Flush()
  • func (c *Cache[K, V]) Get(key K) (V, bool)
  • func (c *Cache[K, V]) GetOrSet(key K, fn func() (V, error), ttl time.Duration) (V, error)
  • func (c *Cache[K, V]) GetWithExpiration(key K) (V, time.Time, bool)
  • func (c *Cache[K, V]) Items() map[K]Item[V]
  • func (c *Cache[K, V]) Replace(key K, val V, ttl time.Duration) error
  • func (c *Cache[K, V]) Set(key K, val V, ttl time.Duration)
  • func (c *Cache[K, V]) SetDefault(key K, val V)
  • func (c *Cache[K, V]) Stop()
• type EvictionPolicy
• type Item
  • func (item Item[V]) Expired() bool
• type Option
  • func WithCleanupInterval[K comparable, V any](d time.Duration) Option[K, V]
  • func WithDefaultTTL[K comparable, V any](d time.Duration) Option[K, V]
  • func WithEviction[K comparable, V any](policy EvictionPolicy) Option[K, V]
  • func WithMaxSize[K comparable, V any](n int) Option[K, V]
  • func WithOnEvicted[K comparable, V any](fn func(K, V)) Option[K, V]
• type ShardedCache
  • func NewSharded[K comparable, V any](shards int, opts ...Option[K, V]) *ShardedCache[K, V]
  • func (sc *ShardedCache[K, V]) Add(key K, val V, ttl time.Duration) error
  • func (sc *ShardedCache[K, V]) Count() int
  • func (sc *ShardedCache[K, V]) Delete(key K)
  • func (sc *ShardedCache[K, V]) DeleteExpired()
  • func (sc *ShardedCache[K, V]) Flush()
  • func (sc *ShardedCache[K, V]) Get(key K) (V, bool)
  • func (sc *ShardedCache[K, V]) GetOrSet(key K, fn func() (V, error), ttl time.Duration) (V, error)
  • func (sc *ShardedCache[K, V]) GetWithExpiration(key K) (V, time.Time, bool)
  • func (sc *ShardedCache[K, V]) Items() map[K]Item[V]
  • func (sc *ShardedCache[K, V]) Replace(key K, val V, ttl time.Duration) error
  • func (sc *ShardedCache[K, V]) Set(key K, val V, ttl time.Duration)
  • func (sc *ShardedCache[K, V]) SetDefault(key K, val V)
  • func (sc *ShardedCache[K, V]) Stop()
• type UntypedCache
  • func NewUntyped(defaultExpiration, cleanupInterval time.Duration) *UntypedCache
  • func (uc *UntypedCache) Decrement(key string, n int64) error
  • func (uc *UntypedCache) Increment(key string, n int64) error

Constants

const DefaultTTL time.Duration = -1

DefaultTTL is a sentinel value indicating that the cache's default TTL should be used.

Variables

var (
	// ErrKeyExists is returned by Add when the key already exists and has not expired.
	ErrKeyExists = errors.New("stash: item already exists")
	// ErrKeyNotFound is returned by Replace when the key does not exist or has expired.
	ErrKeyNotFound = errors.New("stash: item not found")
)

Types

type Cache

type Cache[K comparable, V any] struct {
	// contains filtered or unexported fields
}

Cache is a thread-safe in-memory key-value cache with expiration support.

func New

func New[K comparable, V any](opts ...Option[K, V]) *Cache[K, V]

New creates a new Cache with the given options.

func (*Cache[K, V]) Add

func (c *Cache[K, V]) Add(key K, val V, ttl time.Duration) error

Add sets the item only if the key does not already exist (or has expired). Returns ErrKeyExists if the key is present and not expired.

func (*Cache[K, V]) Count

func (c *Cache[K, V]) Count() int

Count returns the number of items in the cache, including expired items that have not yet been cleaned up.

func (*Cache[K, V]) Delete

func (c *Cache[K, V]) Delete(key K)

Delete removes an item from the cache and fires the onEvicted callback if set.

func (*Cache[K, V]) DeleteExpired

func (c *Cache[K, V]) DeleteExpired()

DeleteExpired removes all expired items from the cache.

func (*Cache[K, V]) Flush

func (c *Cache[K, V]) Flush()

Flush removes all items from the cache.

func (*Cache[K, V]) Get

func (c *Cache[K, V]) Get(key K) (V, bool)

Get returns the value for the given key and whether it was found. Expired items are treated as missing.

func (*Cache[K, V]) GetOrSet

func (c *Cache[K, V]) GetOrSet(key K, fn func() (V, error), ttl time.Duration) (V, error)

GetOrSet returns the existing value for the key if present and not expired. Otherwise, it calls fn to compute the value, stores it, and returns it.

func (*Cache[K, V]) GetWithExpiration

func (c *Cache[K, V]) GetWithExpiration(key K) (V, time.Time, bool)

GetWithExpiration returns the value, its expiration time, and whether it was found. If the item has no expiration, the returned time is the zero value.

func (*Cache[K, V]) Items

func (c *Cache[K, V]) Items() map[K]Item[V]

Items returns a copy of all unexpired items in the cache.

func (*Cache[K, V]) Replace

func (c *Cache[K, V]) Replace(key K, val V, ttl time.Duration) error

Replace sets the item only if the key already exists and has not expired. Returns ErrKeyNotFound if the key is missing or expired.

func (*Cache[K, V]) Set

func (c *Cache[K, V]) Set(key K, val V, ttl time.Duration)

Set adds or updates an item in the cache with the given TTL. Use DefaultTTL to use the cache's default TTL. Use 0 for no expiration.

func (*Cache[K, V]) SetDefault

func (c *Cache[K, V]) SetDefault(key K, val V)

SetDefault adds or updates an item using the cache's default TTL.

func (*Cache[K, V]) Stop

func (c *Cache[K, V]) Stop()

Stop stops the background janitor, if running.

type EvictionPolicy

type EvictionPolicy int

EvictionPolicy defines the eviction strategy when the cache reaches max size.

const (
	// NoEviction means no eviction policy is applied; the cache grows unbounded.
	NoEviction EvictionPolicy = iota
	// LRU evicts the least recently used item.
	LRU
	// LFU evicts the least frequently used item.
	LFU
)

type Item

type Item[V any] struct {
	Value      V
	Expiration int64 // UnixNano timestamp; 0 means no expiry
}

Item represents a cache item with a value and optional expiration.

func (Item[V]) Expired

func (item Item[V]) Expired() bool

Expired returns true if the item has expired.

type Option

type Option[K comparable, V any] func(*config[K, V])

Option is a functional option for configuring a Cache.

func WithCleanupInterval

func WithCleanupInterval[K comparable, V any](d time.Duration) Option[K, V]

WithCleanupInterval sets the interval for the background janitor to remove expired items. A value of 0 disables the janitor.

func WithDefaultTTL

func WithDefaultTTL[K comparable, V any](d time.Duration) Option[K, V]

WithDefaultTTL sets the default TTL for items added without an explicit TTL. A value of 0 means items never expire by default.

func WithEviction

func WithEviction[K comparable, V any](policy EvictionPolicy) Option[K, V]

WithEviction sets the eviction policy for the cache.

func WithMaxSize

func WithMaxSize[K comparable, V any](n int) Option[K, V]

WithMaxSize sets the maximum number of items in the cache. When the limit is reached, the configured eviction policy determines which item is removed. A value of 0 means no limit.

func WithOnEvicted

func WithOnEvicted[K comparable, V any](fn func(K, V)) Option[K, V]

WithOnEvicted sets a callback function that is called when an item is evicted from the cache.

type ShardedCache

type ShardedCache[K comparable, V any] struct {
	// contains filtered or unexported fields
}

ShardedCache is a thread-safe cache that distributes keys across multiple Cache shards to reduce lock contention under high concurrency.

func NewSharded

func NewSharded[K comparable, V any](shards int, opts ...Option[K, V]) *ShardedCache[K, V]

NewSharded creates a new ShardedCache with the given number of shards. Each shard is an independent Cache with the provided options.

func (*ShardedCache[K, V]) Add

func (sc *ShardedCache[K, V]) Add(key K, val V, ttl time.Duration) error

Add sets the item only if the key does not already exist.

func (*ShardedCache[K, V]) Count

func (sc *ShardedCache[K, V]) Count() int

Count returns the total number of items across all shards.

func (*ShardedCache[K, V]) Delete

func (sc *ShardedCache[K, V]) Delete(key K)

Delete removes an item.

func (*ShardedCache[K, V]) DeleteExpired

func (sc *ShardedCache[K, V]) DeleteExpired()

DeleteExpired removes expired items from all shards.

func (*ShardedCache[K, V]) Flush

func (sc *ShardedCache[K, V]) Flush()

Flush removes all items from all shards.

func (*ShardedCache[K, V]) Get

func (sc *ShardedCache[K, V]) Get(key K) (V, bool)

Get returns the value for the given key.

func (*ShardedCache[K, V]) GetOrSet

func (sc *ShardedCache[K, V]) GetOrSet(key K, fn func() (V, error), ttl time.Duration) (V, error)

GetOrSet returns an existing value or computes and stores a new one.

func (*ShardedCache[K, V]) GetWithExpiration

func (sc *ShardedCache[K, V]) GetWithExpiration(key K) (V, time.Time, bool)

GetWithExpiration returns the value and its expiration time.

func (*ShardedCache[K, V]) Items

func (sc *ShardedCache[K, V]) Items() map[K]Item[V]

Items returns a merged copy of all unexpired items across all shards.

func (*ShardedCache[K, V]) Replace

func (sc *ShardedCache[K, V]) Replace(key K, val V, ttl time.Duration) error

Replace sets the item only if the key already exists.

func (*ShardedCache[K, V]) Set

func (sc *ShardedCache[K, V]) Set(key K, val V, ttl time.Duration)

Set adds or updates an item.

func (*ShardedCache[K, V]) SetDefault

func (sc *ShardedCache[K, V]) SetDefault(key K, val V)

SetDefault adds or updates an item using the default TTL.

func (*ShardedCache[K, V]) Stop

func (sc *ShardedCache[K, V]) Stop()

Stop stops the background janitor on all shards.

type UntypedCache

type UntypedCache struct {
	*Cache[string, any]
}

UntypedCache is a Cache[string, any] that provides API compatibility with patrickmn/go-cache. Values are stored as any and must be type-asserted by the caller.

func NewUntyped

func NewUntyped(defaultExpiration, cleanupInterval time.Duration) *UntypedCache

NewUntyped creates a new UntypedCache matching the go-cache constructor signature: cache.New(defaultExpiration, cleanupInterval).

func (*UntypedCache) Decrement

func (uc *UntypedCache) Decrement(key string, n int64) error

Decrement atomically decrements a numeric value by n. The item must exist, not be expired, and hold a supported numeric type.

func (*UntypedCache) Increment

func (uc *UntypedCache) Increment(key string, n int64) error

Increment atomically increments a numeric value by n. The item must exist, not be expired, and hold a supported numeric type.