samber/hot

go get github.com/samber/hot

# AI Agent Skill:
npx skills add https://github.com/samber/cc-skills-golang --skill golang-samber-hot

import "github.com/samber/hot"

cache := hot.NewHotCache[string, int](hot.LRU, 1_000_000).
    WithTTL(10*time.Minute).
    Build()

cache.Set("hello", 42)

values, missing := cache.GetMany([]string{"bar", "baz", "hello"})
// values: {"hello": 42}
// missing: ["baz", "bar"]

// Set default time-to-live for all cache entries
WithTTL(ttl time.Duration)
// Add random jitter to TTL to prevent cache stampedes
WithJitter(lambda float64, upperBound time.Duration)
// Enable background cleanup of expired items
WithJanitor()

// Keep serving stale data while refreshing in background
WithRevalidation(stale time.Duration, loaders ...hot.Loader[K, V])
// Control behavior when revalidation fails (KeepOnError/DropOnError)
WithRevalidationErrorPolicy(policy hot.RevalidationErrorPolicy)

// Use separate cache for missing keys (prevents main cache pollution)
WithMissingCache(algorithm hot.EvictionAlgorithm, capacity int)
// Share missing key cache with main cache (good for low missing rate)
WithMissingSharedCache()

// Set chain of loaders for cache misses (primary, fallback, etc.)
WithLoaders(loaders ...hot.Loader[K, V])

// Disable mutex for single-threaded applications (performance boost)
WithoutLocking()
// Copy values when reading (prevents external modification)
WithCopyOnRead(copier func(V) V)
// Copy values when writing (ensures cache owns the data)
WithCopyOnWrite(copier func(V) V)

// Split cache into multiple shards to reduce lock contention
WithSharding(shards uint64, hasher sharded.Hasher[K])

// Called when items are evicted (LRU/LFU/TinyLFU/W-TinyLFU/S3FIFO/expiration)
WithEvictionCallback(callback func(key K, value V))
// Preload cache on startup with data from loader
WithWarmUp(loader func() (map[K]V, []K, error))
// Preload with timeout protection for slow data sources
WithWarmUpWithTimeout(timeout time.Duration, loader func() (map[K]V, []K, error))

// Enable Prometheus metrics collection with the specified cache name
WithPrometheusMetrics(cacheName string)

hot.LRU
hot.LFU
hot.TinyLFU
hot.WTinyLFU
hot.S3FIFO
hot.TwoQueue
hot.ARC
hot.SIEVE
hot.FIFO

hot.KeepOnError
hot.DropOnError

// Store a key-value pair in the cache
cache.Set(key K, value V)
// Store with custom time-to-live (overrides default TTL)
cache.SetWithTTL(key K, value V, ttl time.Duration)
// Retrieve value by key, returns found status and any error
cache.Get(key K) -> (value V, found bool, error error)
// Check if key exists in cache (no side effects)
cache.Has(key K) -> bool
// Remove key from cache, returns true if key existed
cache.Delete(key K) -> bool

// Store multiple key-value pairs atomically
cache.SetMany(items map[K]V)
// Retrieve multiple values, returns found items and missing keys
cache.GetMany(keys []K) -> (found map[K]V, missing []K)
// Check existence of multiple keys, returns map of key->exists
cache.HasMany(keys []K) -> map[K]bool
// Remove multiple keys, returns map of key->was_deleted
cache.DeleteMany(keys []K) -> map[K]bool

// Get value without updating access time or LRU position
cache.Peek(key K) -> (value V, found bool)
// Get multiple values without side effects
cache.PeekMany(keys []K) -> (found map[K]V, missing []K)
// Get all keys in cache (order not guaranteed)
cache.Keys() -> []K
// Get all values in cache (order not guaranteed)
cache.Values() -> []V
// Get all keys and values in cache (order not guaranteed)
cache.All() -> map[K]V
// Iterate over all key-value pairs, return false to stop
cache.Range(fn func(key K, value V) bool)
// Get current number of items in cache
cache.Len() -> int
// Get (current_size, max_capacity) of cache
cache.Capacity() -> (current int, max int)
// Get (algorithm_name, algorithm_version) info
cache.Algorithm() -> (name string, version string)

// Remove all items from cache immediately
cache.Purge()
// Preload cache with data from loader function
cache.WarmUp(loader hot.Loader[K, V]) -> error
// Start background cleanup of expired items
cache.Janitor()
// Stop background janitor process
cache.StopJanitor()

// Loader function signature for fetching data from external sources
// Called when cache misses occur, with automatic deduplication of concurrent requests
type Loader[K comparable, V any] func(keys []K) (found map[K]V, err error)

// Example:
func userLoader(keys []string) (found map[string]*User, err error) {
    // Fetch users from database
    // Return map of found users (key -> user object)
    // Return empty map if no users found (not an error)
    // Return error if database query fails
    return users, nil
}

// Hasher is responsible for generating unsigned, 16 bit hash of provided key.
// Hasher should minimize collisions. For great performance, a fast function is preferable.
type Hasher[K any] func(key K) uint64

// Example:
func hash(key string) uint64 {
    hasher := fnv.New64a()
    hasher.Write([]byte(s))
    return hasher.Sum64()
}

┌─────────────────────────────────────────────────────────────┐
│                    hot.HotCache[K, V]                       │
│              (High-level, feature-complete)                 │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│              pkg/sharded.ShardedInMemoryCache               │
│                    (Sharding layer)                         │
└─────────────────────────────────────────────────────────────┘
                    │    │    │    │    │
                    ▼    ▼    ▼    ▼    ▼
┌─────────────────────────────────────────────────────────────┐
│              pkg/metrics.InstrumentedCache[K, V]            │
│                   (Metric collection layer)                 │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│              pkg/safe.SafeInMemoryCache[K, V]               │
│                   (Thread safety layer)                     │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│              pkg/lru.LRUCache[K, V]                         │
│              pkg/lfu.LFUCache[K, V]                         │
│              pkg/lfu.TinyLFUCache[K, V]                     │
│              pkg/lfu.WTinyLFUCache[K, V]                    │
│              pkg/lfu.S3FIFOCache[K, V]                      │
│              pkg/arc.ARCCache[K, V]                         │
│              pkg/sieve.SIEVECache[K, V]                     │
│              pkg/fifo.FIFOCache[K, V]                       │
│              pkg/twoqueue.TwoQueueCache[K, V]               │
│                   (Eviction policies)                       │
└─────────────────────────────────────────────────────────────┘

cache := lru.NewLRUCache[string, *User](100_000)

import (
	"github.com/samber/hot/pkg/lfu"
	"github.com/samber/hot/pkg/safe"
)

cache := safe.NewSafeInMemoryCache(
    lru.NewLRUCache[string, *User](100_000),
)

import (
    "hash/fnv"
    "github.com/samber/hot/pkg/lfu"
    "github.com/samber/hot/pkg/safe"
    "github.com/samber/hot/pkg/sharded"
)

cache := sharded.NewShardedInMemoryCache(
    100, // Number of shards
    func() base.InMemoryCache[K, *item[V]] {
        // Cache builder for each shard
        return safe.NewSafeInMemoryCache(
            lru.NewLRUCache[string, *User](100_000),
        )
    },
    func(key string) uint64 {
        // Hash function
        h := fnv.New64a()
        h.Write([]byte(key))
        return h.Sum64()
    },
)

import "github.com/samber/hot"

cache := hot.NewHotCache[string, int](hot.LRU, 100_000).
    WithMissingSharedCache().
    Build()

import "github.com/samber/hot"

cache := hot.NewHotCache[string, int](hot.LRU, 100_000).
    WithMissingCache(hot.LFU, 50_000).
    Build()

import "github.com/samber/hot"

// Available eviction policies: hot.LRU, hot.LFU, hot.TinyLFU, hot.WTinyLFU, hot.S3FIFO, hot.TwoQueue, hot.ARC, hot.SIEVE, hot.FIFO
// Capacity: 100k keys/values
cache := hot.NewHotCache[string, int](hot.LRU, 100_000).
    Build()

cache.Set("hello", 42)
cache.SetMany(map[string]int{"foo": 1, "bar": 2})

values, missing := cache.GetMany([]string{"bar", "baz", "hello"})
// values: {"bar": 2, "hello": 42}
// missing: ["baz"]

value, found, _ := cache.Get("foo")
// value: 1
// found: true

// Handle cache operations with proper error checking
value, found, err := cache.Get("key")
if err != nil {
    // Handle loader errors (database connection, network issues, etc.)
    log.Printf("Cache get error: %v", err)
    return
}
if !found {
    // Key doesn't exist in cache and wasn't found by loaders
    log.Printf("Key not found: %s", "key")
    return
}
// Use value safely
fmt.Printf("Value: %v", value)

// Batch operations with error handling
values, missing := cache.GetMany([]string{"key1", "key2", "key3"})
if len(missing) > 0 {
    log.Printf("Missing keys: %v", missing)
}
// Process found values
for key, value := range values {
    fmt.Printf("%s: %v", key, value)
}

import "github.com/samber/hot"

cache := hot.NewHotCache[string, *User](hot.LRU, 100_000).
    WithLoaders(func(keys []string) (found map[string]*User, err error) {
        rows, err := db.Query("SELECT * FROM users WHERE id IN (?)", keys)
        // ...
        return users, err
    }).
    Build()

user, found, err := cache.Get("user-123")
// might fail if "user-123" is not in cache and loader returns error

// get or create
user, found, err := cache.GetWithLoaders(
    "user-123",
    func(keys []string) (found map[string]*User, err error) {
        rows, err := db.Query("SELECT * FROM users WHERE id IN (?)", keys)
        // ...
        return users, err
    },
    func(keys []string) (found map[string]*User, err error) {
        rows, err := db.Query("INSERT INTO users (id, email) VALUES (?, ?)", id, email)
        // ...
        return users, err
    },
)
// either `err` is not nil, or `found` is true

// missing value vs nil value
user, found, err := cache.GetWithLoaders(
    "user-123",
    func(keys []string) (found map[string]*User, err error) {
        // value could not be found
        return map[string]*User{}, nil

       // or

        // value exists but is nil
        return map[string]*User{"user-123": nil}, nil
    },
)

import "github.com/samber/hot"

cache := hot.NewHotCache[string, int](hot.LRU, 100_000).
    WithTTL(1 * time.Minute).      // items will expire after 1 minute
    WithJitter(2, 30*time.Second). // optional: randomizes the TTL with an exponential distribution in the range [0, +30s)
    WithJanitor(1 * time.Minute).  // optional: background job will purge expired keys every minutes
    Build()

cache.SetWithTTL("foo", 42, 10*time.Second) // shorter TTL for "foo" key

loader := func(keys []string) (found map[string]*User, err error) {
    rows, err := db.Query("SELECT * FROM users WHERE id IN (?)", keys)
    // ...
    return users, err
}

cache := hot.NewHotCache[string, *User](hot.LRU, 100_000).
    WithTTL(1 * time.Minute).
    // Keep delivering cache 5 more second, but refresh value in background.
    // Keys that are not fetched during the interval will be dropped anyway.
    // A timeout or error in loader will drop keys.
    WithRevalidation(5 * time.Second, loader).
    // On revalidation error, the cache entries are either kept or dropped.
    // Optional (default: drop)
    WithRevalidationErrorPolicy(hot.KeepOnError).
    Build()

import (
    "github.com/prometheus/client_golang/prometheus"
    "github.com/prometheus/client_golang/prometheus/promhttp"
    "github.com/samber/hot"
    "net/http"
)

// Create cache with Prometheus metrics
cache := hot.NewHotCache[string, string](hot.LRU, 1000).
    WithTTL(5*time.Minute).
    WithJitter(0.5, 10*time.Second).
    WithRevalidation(10*time.Second).
    WithRevalidationErrorPolicy(hot.KeepOnError).
    WithPrometheusMetrics("users-by-id").
    WithMissingCache(hot.ARC, 1000).
    Build()

// Register the cache metrics with Prometheus
err := prometheus.Register(cache)
if err != nil {
    log.Fatalf("Failed to register metrics: %v", err)
}
defer prometheus.Unregister(cache)

// Set up HTTP server to expose metrics
http.Handle("/metrics", promhttp.Handler())
http.ListenAndServe(":8080", nil)

# Cache hit ratio
rate(hot_hit_total[5m]) / (rate(hot_hit_total[5m]) + rate(hot_miss_total[5m]))

# Eviction rate by reason
rate(hot_eviction_total[5m])

# Cache size in MB
hot_size_bytes / 1024 / 1024

# Cache utilization percentage
hot_length / hot_settings_capacity * 100

# Insertion rate
rate(hot_insertion_total[5m])

# Install some dev dependencies
make tools

# Run tests
make test
# or
make watch-test