cache

cache gives your services one cache API with multiple backend options. Swap drivers without refactoring.

What cache is

An explicit cache abstraction with a minimal Store interface and ergonomic Cache helpers. Drivers are chosen when you construct the store, so swapping backends is a dependency-injection change instead of a refactor.

Drivers

Driver / Backend	Mode	Shared	Durable	TTL	Counters	Notes
	No-op	-	-	-	-	Great for tests: cache calls are no-ops and never persist.
	Local filesystem	-	✓	✓	✓	Simple durability on a single host; point WithFileDir to writable disk.
	In-process	-	-	✓	✓	Fastest; per-process only, best for single-node or short-lived data.
	Networked	✓	-	✓	✓	Millisecond access; TTL resolution is 1s; use multiple nodes via WithMemcachedAddresses.
	Networked	✓	-	✓	✓	Full feature set; supports prefixing and counters with per-key TTL refresh.
	Networked	✓	-	✓	✓	JetStream KeyValue-backed driver; inject an existing bucket via WithNATSKeyValue.
	Networked	✓	✓	✓	✓	Backed by DynamoDB (supports localstack/dynamodb-local).
	Networked / local	✓	✓	✓	✓	Postgres / MySQL / SQLite via database/sql; table schema managed automatically.

Installation

go get github.com/goforj/cache

Quick Start

import (
    "context"
    "time"

    "github.com/goforj/cache"
    "github.com/redis/go-redis/v9"
)

func main() {
    ctx := context.Background()

    store := cache.NewMemoryStore(ctx, cache.WithDefaultTTL(5*time.Minute))
    c := cache.NewCache(store)

    // Remember pattern.
    type Profile struct { Name string `json:"name"` }

    profile, err := cache.Remember[Profile](c, "user:42:profile", time.Minute, func() (Profile, error) {
        return Profile{Name: "Ada"}, nil
    })
    fmt.Println(profile.Name) // Ada

    // Switch to Redis (dependency injection, no code changes below).
    client := redis.NewClient(&redis.Options{Addr: "127.0.0.1:6379"})
    store = cache.NewRedisStore(ctx, client, cache.WithPrefix("app"), cache.WithDefaultTTL(5*time.Minute))
    c = cache.NewCache(store)
}

StoreConfig

StoreConfig keeps configuration explicit:

• Driver: explicit backend (null, file, memory, memcached, redis, nats, dynamodb, sql)
• DefaultTTL: fallback TTL when a call provides ttl <= 0
• MemoryCleanupInterval: sweep interval for memory driver
• Prefix: key prefix for shared backends
• RedisClient / NATSKeyValue / MemcachedAddresses / DynamoClient / SQLDriverName+DSN: driver-specific inputs
• Compression / MaxValueBytes / EncryptionKey: shaping and security controls

Behavior Semantics

For precise runtime semantics, see Behavior Semantics:

• TTL/default-TTL matrix by operation/helper
• stale and refresh-ahead behavior and edge cases
• lock and rate-limit guarantees (process-local vs distributed scope)

Production Guidance

For deployment defaults and operational patterns, see Production Guide:

• recommended defaults and tuning
• key naming/versioning conventions
• TTL jitter and miss-storm mitigation
• observability instrumentation patterns

Memoized reads

Wrap any store with NewMemoStore to memoize reads within the process; cache is invalidated automatically on write paths.

memoStore := cache.NewMemoStore(store)
memoRepo := cache.NewCache(memoStore)

Staleness note: memoization is per-process only. Writes that happen in other processes (or outside your app) will not invalidate this memo cache. Use it when local staleness is acceptable, or scope it narrowly (e.g., per-request) if multiple writers exist.

Testing

Unit tests cover the public helpers. Integration tests use testcontainers-go to spin up Redis:

go test -tags=integration ./...

Use INTEGRATION_DRIVER=redis (comma-separated; defaults to all) to select which drivers start containers and run the contract suite.

Benchmarks

go test ./docs/bench -tags benchrender

Note: NATS numbers can look slower than Redis/memory because the NATS driver preserves per-operation TTL semantics by storing per-key expiry metadata (envelope encode/decode) and may do extra compare/update steps for some operations.

Note: DynamoDB is intentionally omitted from these local charts because emulator-based numbers are not representative of real AWS latency.

NATS variants in these charts:

• nats: per-key TTL semantics using a binary envelope (magic/expiresAt/value). This preserves per-key expiry parity with other drivers, with modest metadata overhead.
• nats_bucket_ttl: bucket-level TTL mode (WithNATSBucketTTL(true)), raw value path; faster but different expiry semantics.

Latency (ns/op)

Iterations (N)

Allocated Bytes (B/op)

Allocations (allocs/op)

Testing helpers

For unit tests that shouldn’t hit real infrastructure, use the in-memory fake with call assertions:

f := cachefake.New()
c := f.Cache()

// exercise code under test
_ = c.SetString("settings:mode", "dark", 0)
_, _, _ = c.Get("settings:mode")
_ = c.Delete("settings:mode")

f.AssertCalled(t, cachefake.OpSet, "settings:mode", 1)
f.AssertCalled(t, cachefake.OpGet, "settings:mode", 1)
f.AssertCalled(t, cachefake.OpDelete, "settings:mode", 1)
f.AssertNotCalled(t, cachefake.OpAdd, "settings:mode")

API reference

The API section below is autogenerated; do not edit between the markers.

API Index

Group	Functions
Constructors	NewDynamoStore NewFileStore NewMemcachedStore NewMemoryStore NewNATSStore NewNullStore NewRedisStore NewSQLStore NewStore NewStoreWith
Core	Driver NewCache NewCacheWithTTL Store
Invalidation	Delete DeleteCtx DeleteMany DeleteManyCtx Flush FlushCtx Pull PullCtx
Locking	Lock LockCtx TryLock TryLockCtx Unlock UnlockCtx
Memoization	NewMemoStore
Observability	WithObserver
Options	WithCompression WithDefaultTTL WithDynamoClient WithDynamoEndpoint WithDynamoRegion WithDynamoTable WithEncryptionKey WithFileDir WithMaxValueBytes WithMemcachedAddresses WithMemoryCleanupInterval WithNATSBucketTTL WithNATSKeyValue WithPrefix WithRedisClient WithSQL
Rate Limiting	RateLimit RateLimitCtx RateLimitWithRemaining RateLimitWithRemainingCtx
Read Through	Remember RememberBytes RememberCtx RememberJSON RememberJSONCtx RememberStale RememberStaleBytes RememberStaleBytesCtx RememberStaleCtx RememberStaleValueWithCodec RememberString RememberStringCtx RememberValue RememberValueWithCodec
Reads	BatchGet BatchGetCtx Get GetCtx GetJSON GetJSONCtx GetString GetStringCtx
Refresh Ahead	RefreshAhead RefreshAheadCtx RefreshAheadValueWithCodec
Writes	Add AddCtx BatchSet BatchSetCtx Decrement DecrementCtx Increment IncrementCtx Set SetCtx SetJSON SetJSONCtx SetString SetStringCtx

Constructors

NewDynamoStore

NewDynamoStore is a convenience for a DynamoDB-backed store.

ctx := context.Background()
store := cache.NewDynamoStore(ctx, cache.StoreConfig{DynamoEndpoint: "http://localhost:8000"})
fmt.Println(store.Driver()) // dynamodb

NewFileStore

NewFileStore is a convenience for a filesystem-backed store.

ctx := context.Background()
store := cache.NewFileStore(ctx, "/tmp/my-cache")
fmt.Println(store.Driver()) // file

NewMemcachedStore

NewMemcachedStore is a convenience for a memcached-backed store.

ctx := context.Background()
store := cache.NewMemcachedStore(ctx, []string{"127.0.0.1:11211"})
fmt.Println(store.Driver()) // memcached

NewMemoryStore

NewMemoryStore is a convenience for an in-process store with optional overrides.

ctx := context.Background()
store := cache.NewMemoryStore(ctx)
fmt.Println(store.Driver()) // memory

NewNATSStore

NewNATSStore is a convenience for a NATS JetStream KeyValue-backed store.

ctx := context.Background()
var kv cache.NATSKeyValue // provided by your NATS setup
store := cache.NewNATSStore(ctx, kv, cache.WithPrefix("app"))
fmt.Println(store.Driver()) // nats

NewNullStore

NewNullStore is a no-op store useful for tests where caching should be disabled.

ctx := context.Background()
store := cache.NewNullStore(ctx)
fmt.Println(store.Driver()) // null

NewRedisStore

NewRedisStore is a convenience for a redis-backed store. Redis client is required.

ctx := context.Background()
redisClient := redis.NewClient(&redis.Options{Addr: "127.0.0.1:6379"})
store := cache.NewRedisStore(ctx, redisClient, cache.WithPrefix("app"))
fmt.Println(store.Driver()) // redis

NewSQLStore

NewSQLStore builds a SQL-backed store (postgres, mysql, sqlite).

Example: sqlite helper

ctx := context.Background()
store := cache.NewSQLStore(ctx, "sqlite", "file:cache.db?cache=shared&mode=rwc", "cache_entries")
fmt.Println(store.Driver()) // sql

Example: postgres helper

dsnPg := "postgres://user:pass@localhost:5432/app?sslmode=disable"
storePg := cache.NewSQLStore(ctx, "pgx", dsnPg, "cache_entries")
fmt.Println(storePg.Driver()) // sql

Example: mysql helper

dsnMy := "user:pass@tcp(localhost:3306)/app?parseTime=true"
storeMy := cache.NewSQLStore(ctx, "mysql", dsnMy, "cache_entries")
fmt.Println(storeMy.Driver()) // sql

NewStore

NewStore returns a concrete store for the requested driver. Caller is responsible for providing any driver-specific dependencies.

ctx := context.Background()
store := cache.NewStore(ctx, cache.StoreConfig{
	Driver: cache.DriverMemory,
})
fmt.Println(store.Driver()) // memory

NewStoreWith

NewStoreWith builds a store using a driver and a set of functional options. Required data (e.g., Redis client) must be provided via options when needed.

Example: memory store (options)

ctx := context.Background()
store := cache.NewStoreWith(ctx, cache.DriverMemory)
fmt.Println(store.Driver()) // memory

Example: redis store (options)

redisClient := redis.NewClient(&redis.Options{Addr: "127.0.0.1:6379"})
store = cache.NewStoreWith(ctx, cache.DriverRedis,
	cache.WithRedisClient(redisClient),
	cache.WithPrefix("app"),
	cache.WithDefaultTTL(5*time.Minute),
)
fmt.Println(store.Driver()) // redis

Core

Driver

Driver reports the underlying store driver.

NewCache

NewCache creates a cache facade bound to a concrete store.

ctx := context.Background()
s := cache.NewMemoryStore(ctx)
c := cache.NewCache(s)
fmt.Println(c.Driver()) // memory

NewCacheWithTTL

NewCacheWithTTL lets callers override the default TTL applied when ttl <= 0.

ctx := context.Background()
s := cache.NewMemoryStore(ctx)
c := cache.NewCacheWithTTL(s, 2*time.Minute)
fmt.Println(c.Driver(), c != nil) // memory true

Store

Store returns the underlying store implementation.

ctx := context.Background()
c := cache.NewCache(cache.NewMemoryStore(ctx))
fmt.Println(c.Store().Driver()) // memory

Invalidation

Delete

Delete removes a single key.

ctx := context.Background()
c := cache.NewCache(cache.NewMemoryStore(ctx))
fmt.Println(c.Delete("a") == nil) // true

DeleteCtx

DeleteCtx is the context-aware variant of Delete.

DeleteMany

DeleteMany removes multiple keys.

ctx := context.Background()
c := cache.NewCache(cache.NewMemoryStore(ctx))
fmt.Println(c.DeleteMany("a", "b") == nil) // true

DeleteManyCtx

DeleteManyCtx is the context-aware variant of DeleteMany.

Flush

Flush clears all keys for this store scope.

ctx := context.Background()
c := cache.NewCache(cache.NewMemoryStore(ctx))
fmt.Println(c.Flush() == nil) // true

FlushCtx

FlushCtx is the context-aware variant of Flush.

Pull

Pull returns value and removes it from cache.

ctx := context.Background()
c := cache.NewCache(cache.NewMemoryStore(ctx))
body, ok, _ := c.Pull("reset:token:42")
fmt.Println(ok, string(body)) // true abc

PullCtx

PullCtx is the context-aware variant of Pull.

Locking

Lock

Lock waits until the lock is acquired or timeout elapses.

ctx := context.Background()
c := cache.NewCache(cache.NewMemoryStore(ctx))
locked, err := c.Lock("job:sync", 10*time.Second, time.Second)
fmt.Println(err == nil, locked) // true true

LockCtx

LockCtx retries lock acquisition until success or context cancellation.

TryLock

TryLock acquires a short-lived lock key when not already held.

ctx := context.Background()
c := cache.NewCache(cache.NewMemoryStore(ctx))
locked, _ := c.TryLock("job:sync", 10*time.Second)
fmt.Println(locked) // true

TryLockCtx

TryLockCtx is the context-aware variant of TryLock.

Unlock

Unlock releases a previously acquired lock key.

ctx := context.Background()
c := cache.NewCache(cache.NewMemoryStore(ctx))
locked, _ := c.TryLock("job:sync", 10*time.Second)
if locked {
}

UnlockCtx

UnlockCtx is the context-aware variant of Unlock.

Memoization

NewMemoStore

NewMemoStore decorates store with per-process read memoization.

Behavior:

• First Get hits the backing store, clones the value, and memoizes it in-process.
• Subsequent Get for the same key returns the memoized clone (no backend call).
• Any write/delete/flush invalidates the memo entry so local reads stay in sync with changes made through this process.
• Memo data is per-process only; other processes or external writers will not invalidate it. Use only when that staleness window is acceptable.

ctx := context.Background()
base := cache.NewMemoryStore(ctx)
memo := cache.NewMemoStore(base)
c := cache.NewCache(memo)
fmt.Println(c.Driver()) // memory

Observability

WithObserver

WithObserver attaches an observer to receive operation events.

Options

WithCompression

WithCompression enables value compression using the chosen codec.

ctx := context.Background()
store := cache.NewStoreWith(ctx, cache.DriverMemory, cache.WithCompression(cache.CompressionGzip))
fmt.Println(store.Driver()) // memory

WithDefaultTTL

WithDefaultTTL overrides the fallback TTL used when ttl <= 0.

ctx := context.Background()
store := cache.NewStoreWith(ctx, cache.DriverMemory, cache.WithDefaultTTL(30*time.Second))
fmt.Println(store.Driver()) // memory

WithDynamoClient

WithDynamoClient injects a pre-built DynamoDB client.

ctx := context.Background()
var client cache.DynamoAPI // assume already configured
store := cache.NewStoreWith(ctx, cache.DriverDynamo, cache.WithDynamoClient(client))
fmt.Println(store.Driver()) // dynamodb

WithDynamoEndpoint

WithDynamoEndpoint sets the DynamoDB endpoint (useful for local testing).

ctx := context.Background()
store := cache.NewStoreWith(ctx, cache.DriverDynamo, cache.WithDynamoEndpoint("http://localhost:8000"))
fmt.Println(store.Driver()) // dynamodb

WithDynamoRegion

WithDynamoRegion sets the DynamoDB region for requests.

ctx := context.Background()
store := cache.NewStoreWith(ctx, cache.DriverDynamo, cache.WithDynamoRegion("us-west-2"))
fmt.Println(store.Driver()) // dynamodb

WithDynamoTable

WithDynamoTable sets the table used by the DynamoDB driver.

ctx := context.Background()
store := cache.NewStoreWith(ctx, cache.DriverDynamo, cache.WithDynamoTable("cache_entries"))
fmt.Println(store.Driver()) // dynamodb

WithEncryptionKey

WithEncryptionKey enables at-rest encryption using the provided AES key (16/24/32 bytes).

ctx := context.Background()
key := []byte("01234567890123456789012345678901")
store := cache.NewStoreWith(ctx, cache.DriverFile, cache.WithEncryptionKey(key))
fmt.Println(store.Driver()) // file

WithFileDir

WithFileDir sets the directory used by the file driver.

ctx := context.Background()
store := cache.NewStoreWith(ctx, cache.DriverFile, cache.WithFileDir("/tmp/cache"))
fmt.Println(store.Driver()) // file

WithMaxValueBytes

WithMaxValueBytes sets a per-entry size limit (0 disables the check).

ctx := context.Background()
store := cache.NewStoreWith(ctx, cache.DriverMemory, cache.WithMaxValueBytes(1024))
fmt.Println(store.Driver()) // memory

WithMemcachedAddresses

WithMemcachedAddresses sets memcached server addresses (host:port).

ctx := context.Background()
store := cache.NewStoreWith(ctx, cache.DriverMemcached, cache.WithMemcachedAddresses("127.0.0.1:11211"))
fmt.Println(store.Driver()) // memcached

WithMemoryCleanupInterval

WithMemoryCleanupInterval overrides the sweep interval for the memory driver.

ctx := context.Background()
store := cache.NewStoreWith(ctx, cache.DriverMemory, cache.WithMemoryCleanupInterval(5*time.Minute))
fmt.Println(store.Driver()) // memory

WithNATSBucketTTL

WithNATSBucketTTL toggles bucket-level TTL mode for DriverNATS. When enabled, values are stored as raw bytes and per-operation ttl values are ignored.

ctx := context.Background()
var kv cache.NATSKeyValue // provided by your NATS setup
store := cache.NewStoreWith(ctx, cache.DriverNATS,
	cache.WithNATSKeyValue(kv),
	cache.WithNATSBucketTTL(true),
)
fmt.Println(store.Driver()) // nats

WithNATSKeyValue

WithNATSKeyValue sets the NATS JetStream KeyValue bucket; required when using DriverNATS.

ctx := context.Background()
var kv cache.NATSKeyValue // provided by your NATS setup
store := cache.NewStoreWith(ctx, cache.DriverNATS, cache.WithNATSKeyValue(kv))
fmt.Println(store.Driver()) // nats

WithPrefix

WithPrefix sets the key prefix for shared backends (e.g., redis).

ctx := context.Background()
store := cache.NewStoreWith(ctx, cache.DriverRedis, cache.WithPrefix("svc"))
fmt.Println(store.Driver()) // redis

WithRedisClient

WithRedisClient sets the redis client; required when using DriverRedis.

ctx := context.Background()
rdb := redis.NewClient(&redis.Options{Addr: "127.0.0.1:6379"})
store := cache.NewStoreWith(ctx, cache.DriverRedis, cache.WithRedisClient(rdb))
fmt.Println(store.Driver()) // redis

WithSQL

WithSQL configures the SQL driver (driver name + DSN + optional table).

ctx := context.Background()
store := cache.NewStoreWith(ctx, cache.DriverSQL,
	cache.WithSQL("sqlite", "file::memory:?cache=shared", "cache_entries"),
	cache.WithPrefix("svc"),
)
fmt.Println(store.Driver()) // sql

Rate Limiting

RateLimit

RateLimit increments key in a fixed window and reports whether requests are allowed.

ctx := context.Background()
c := cache.NewCache(cache.NewMemoryStore(ctx))
allowed, count, _ := c.RateLimit("rl:login:user:42", 5, time.Minute)
fmt.Println(allowed, count >= 1) // true true

RateLimitCtx

RateLimitCtx is the context-aware variant of RateLimit.

RateLimitWithRemaining

RateLimitWithRemaining increments a fixed-window counter and returns allowance metadata.

ctx := context.Background()
c := cache.NewCache(cache.NewMemoryStore(ctx))
allowed, count, remaining, resetAt, err := c.RateLimitWithRemaining("rl:api:ip:1.2.3.4", 100, time.Minute)
fmt.Println(err == nil, allowed, count >= 1, remaining >= 0, resetAt.After(time.Now()))

RateLimitWithRemainingCtx

RateLimitWithRemainingCtx is the context-aware variant of RateLimitWithRemaining.

Read Through

Remember

Remember is the ergonomic, typed remember helper using JSON encoding by default.

type Profile struct { Name string `json:"name"` }
ctx := context.Background()
c := cache.NewCache(cache.NewMemoryStore(ctx))
profile, err := cache.Remember[Profile](c, "profile:42", time.Minute, func() (Profile, error) {
	return Profile{Name: "Ada"}, nil
})
fmt.Println(err == nil, profile.Name) // true Ada

RememberBytes

RememberBytes returns key value or computes/stores it when missing.

ctx := context.Background()
c := cache.NewCache(cache.NewMemoryStore(ctx))
data, err := c.RememberBytes("dashboard:summary", time.Minute, func() ([]byte, error) {
	return []byte("payload"), nil
})
fmt.Println(err == nil, string(data)) // true payload

RememberCtx

RememberCtx is the context-aware variant of RememberBytes.

RememberJSON

RememberJSON returns key value or computes/stores JSON when missing.

type Settings struct { Enabled bool `json:"enabled"` }
ctx := context.Background()
c := cache.NewCache(cache.NewMemoryStore(ctx))
settings, err := cache.RememberJSON[Settings](c, "settings:alerts", time.Minute, func() (Settings, error) {
	return Settings{Enabled: true}, nil
})
fmt.Println(err == nil, settings.Enabled) // true true

RememberJSONCtx

RememberJSONCtx is the context-aware variant of RememberJSON.

RememberStale

RememberStale returns a typed value with stale fallback semantics using JSON encoding by default.

type Profile struct { Name string `json:"name"` }
ctx := context.Background()
c := cache.NewCache(cache.NewMemoryStore(ctx))
profile, usedStale, err := cache.RememberStale[Profile](c, "profile:42", time.Minute, 10*time.Minute, func() (Profile, error) {
	return Profile{Name: "Ada"}, nil
})
fmt.Println(err == nil, usedStale, profile.Name) // true false Ada

RememberStaleBytes

RememberStaleBytes returns a fresh value when available, otherwise computes and caches it. If computing fails and a stale value exists, it returns the stale value. The returned bool is true when a stale fallback was used.

ctx := context.Background()
c := cache.NewCache(cache.NewMemoryStore(ctx))
body, usedStale, err := c.RememberStaleBytes("profile:42", time.Minute, 10*time.Minute, func() ([]byte, error) {
	return []byte(`{"name":"Ada"}`), nil
})
fmt.Println(err == nil, usedStale, len(body) > 0)

RememberStaleBytesCtx

RememberStaleBytesCtx is the context-aware variant of RememberStaleBytes.

RememberStaleCtx

RememberStaleCtx returns a typed value with stale fallback semantics using JSON encoding by default.

type Profile struct { Name string `json:"name"` }
ctx := context.Background()
c := cache.NewCache(cache.NewMemoryStore(ctx))
profile, usedStale, err := cache.RememberStaleCtx[Profile](ctx, c, "profile:42", time.Minute, 10*time.Minute, func(ctx context.Context) (Profile, error) {
	return Profile{Name: "Ada"}, nil
})
fmt.Println(err == nil, usedStale, profile.Name) // true false Ada

RememberStaleValueWithCodec

RememberStaleValueWithCodec allows custom encoding/decoding for typed stale remember operations.

type Profile struct { Name string }
codec := cache.ValueCodec[Profile]{
	Encode: func(v Profile) ([]byte, error) { return []byte(v.Name), nil },
	Decode: func(b []byte) (Profile, error) { return Profile{Name: string(b)}, nil },
}
ctx := context.Background()
c := cache.NewCache(cache.NewMemoryStore(ctx))
profile, usedStale, err := cache.RememberStaleValueWithCodec(ctx, c, "profile:42", time.Minute, 10*time.Minute, func() (Profile, error) {
	return Profile{Name: "Ada"}, nil
}, codec)
fmt.Println(err == nil, usedStale, profile.Name) // true false Ada

RememberString

RememberString returns key value or computes/stores it when missing.

ctx := context.Background()
c := cache.NewCache(cache.NewMemoryStore(ctx))
val, err := c.RememberString("settings:mode", time.Minute, func() (string, error) {
	return "on", nil
})
fmt.Println(err == nil, val) // true on

RememberStringCtx

RememberStringCtx is the context-aware variant of RememberString.

RememberValue

RememberValue returns a typed value or computes/stores it when missing using JSON encoding by default.

type Summary struct { Text string `json:"text"` }
ctx := context.Background()
c := cache.NewCache(cache.NewMemoryStore(ctx))
s, err := cache.RememberValue[Summary](c, "dashboard:summary", time.Minute, func() (Summary, error) {
	return Summary{Text: "ok"}, nil
})
fmt.Println(err == nil, s.Text) // true ok

RememberValueWithCodec

RememberValueWithCodec allows custom encoding/decoding for typed remember operations.

Reads

BatchGet

BatchGet returns all found values for the provided keys. Missing keys are omitted from the returned map.

ctx := context.Background()
c := cache.NewCache(cache.NewMemoryStore(ctx))
values, err := c.BatchGet("a", "b", "missing")
fmt.Println(err == nil, string(values["a"]), string(values["b"])) // true 1 2

BatchGetCtx

BatchGetCtx is the context-aware variant of BatchGet.

Get

Get returns raw bytes for key when present.

ctx := context.Background()
s := cache.NewMemoryStore(ctx)
c := cache.NewCache(s)
value, ok, _ := c.Get("user:42")
fmt.Println(ok, string(value)) // true Ada

GetCtx

GetCtx is the context-aware variant of Get.

GetJSON

GetJSON decodes a JSON value into T when key exists, using background context.

type Profile struct { Name string `json:"name"` }
ctx := context.Background()
c := cache.NewCache(cache.NewMemoryStore(ctx))
profile, ok, err := cache.GetJSON[Profile](c, "profile:42")
fmt.Println(err == nil, ok, profile.Name) // true true Ada

GetJSONCtx

GetJSONCtx is the context-aware variant of GetJSON.

GetString

GetString returns a UTF-8 string value for key when present.

ctx := context.Background()
c := cache.NewCache(cache.NewMemoryStore(ctx))
name, ok, _ := c.GetString("user:42:name")
fmt.Println(ok, name) // true Ada

GetStringCtx

GetStringCtx is the context-aware variant of GetString.

Refresh Ahead

RefreshAhead

RefreshAhead returns cached value immediately and refreshes asynchronously when near expiry. On miss, it computes and stores synchronously.

Example: refresh ahead

ctx := context.Background()
c := cache.NewCache(cache.NewMemoryStore(ctx))
body, err := c.RefreshAhead("dashboard:summary", time.Minute, 10*time.Second, func() ([]byte, error) {
	return []byte("payload"), nil
})
fmt.Println(err == nil, len(body) > 0) // true true

Example: refresh ahead typed

type Summary struct { Text string `json:"text"` }
ctx := context.Background()
c := cache.NewCache(cache.NewMemoryStore(ctx))
s, err := cache.RefreshAhead[Summary](c, "dashboard:summary", time.Minute, 10*time.Second, func() (Summary, error) {
	return Summary{Text: "ok"}, nil
})
fmt.Println(err == nil, s.Text) // true ok

RefreshAheadCtx

RefreshAheadCtx is the context-aware variant of RefreshAhead.

RefreshAheadValueWithCodec

RefreshAheadValueWithCodec allows custom encoding/decoding for typed refresh-ahead operations.

Writes

Add

Add writes value only when key is not already present.

ctx := context.Background()
c := cache.NewCache(cache.NewMemoryStore(ctx))
created, _ := c.Add("boot:seeded", []byte("1"), time.Hour)
fmt.Println(created) // true

AddCtx

AddCtx is the context-aware variant of Add.

BatchSet

BatchSet writes many key/value pairs using a shared ttl.

ctx := context.Background()
c := cache.NewCache(cache.NewMemoryStore(ctx))
err := c.BatchSet(map[string][]byte{
	"a": []byte("1"),
	"b": []byte("2"),
}, time.Minute)
fmt.Println(err == nil) // true

BatchSetCtx

BatchSetCtx is the context-aware variant of BatchSet.

Decrement

Decrement decrements a numeric value and returns the result.

ctx := context.Background()
c := cache.NewCache(cache.NewMemoryStore(ctx))
val, _ := c.Decrement("rate:login:42", 1, time.Minute)
fmt.Println(val) // -1

DecrementCtx

DecrementCtx is the context-aware variant of Decrement.

Increment

Increment increments a numeric value and returns the result.

ctx := context.Background()
c := cache.NewCache(cache.NewMemoryStore(ctx))
val, _ := c.Increment("rate:login:42", 1, time.Minute)
fmt.Println(val) // 1

IncrementCtx

IncrementCtx is the context-aware variant of Increment.

Set

Set writes raw bytes to key.

ctx := context.Background()
c := cache.NewCache(cache.NewMemoryStore(ctx))
fmt.Println(c.Set("token", []byte("abc"), time.Minute) == nil) // true

SetCtx

SetCtx is the context-aware variant of Set.

SetJSON

SetJSON encodes value as JSON and writes it to key using background context.

type Settings struct { Enabled bool `json:"enabled"` }
ctx := context.Background()
c := cache.NewCache(cache.NewMemoryStore(ctx))
err := cache.SetJSON(c, "settings:alerts", Settings{Enabled: true}, time.Minute)
fmt.Println(err == nil) // true

SetJSONCtx

SetJSONCtx is the context-aware variant of SetJSON.

SetString

SetString writes a string value to key.

ctx := context.Background()
c := cache.NewCache(cache.NewMemoryStore(ctx))
fmt.Println(c.SetString("user:42:name", "Ada", time.Minute) == nil) // true

SetStringCtx

SetStringCtx is the context-aware variant of SetString.