go-cache

go-cache is a thread-safe, in-memory key-value store for Go, built around a simple map[string]interface{} guarded by a sync.RWMutex, with per-item expiration times. It behaves like a single-process Memcached: any Go value can be cached forever or for a set duration without the overhead of serializing data or making network round-trips to an external cache server.

Expired items are automatically purged by a background janitor goroutine on a configurable interval, and the entire cache can be saved to and restored from disk using gob encoding — useful for surviving short-lived restarts without a cold cache. An experimental sharded cache implementation is also included (unexported, opt-in via the package’s internal APIs) for workloads that need finer-grained locking than the single-mutex default.

What You Get

• A generic Cache type usable with any Go value via interface{}, with Set/Get/GetWithExpiration/Delete and typed Increment/Decrement helpers for every numeric kind.
• Configurable default expiration and cleanup interval, set once at construction time with New() or NewFrom().
• Optional persistence to disk (or any io.Writer) via gob encoding through Save/SaveFile and Load/LoadFile.
• An OnEvicted callback hook fired on delete or expiry, plus an experimental sharded cache variant for high-concurrency scenarios.

Common Use Cases

• Caching expensive computed responses or database query results in a single-process API service without standing up Redis or Memcached.
• Tracking per-key counters (rate limits, request counts) with Increment/IncrementInt and an expiration window that resets automatically.
• Storing short-lived session data or parsed auth tokens with expirations that mirror the token’s own TTL.
• Persisting a long-running worker’s in-memory cache to disk with SaveFile so it can reload with LoadFile after a deploy or crash.

Under The Hood

Architecture The package is a single cache package split across two files: cache.go holds the primary implementation and sharded.go an experimental, currently-unexported sharded variant. The public Cache type wraps an internal *cache struct purely so runtime.SetFinalizer can stop the background janitor goroutine when the wrapper is garbage-collected — a deliberate embedding trick called out directly in the source comments. All state lives behind a single sync.RWMutex; read paths (Get, GetWithExpiration) take a read lock and inline the expiration check to avoid an extra function call, while writes (Set, Add, Replace, the typed Increment*/Decrement* family) take the write lock. The sharded variant in sharded.go distributes keys across N independent *cache buckets chosen by a custom djb33 hash, so a change to the core cache struct’s locking model would also need to stay consistent with the sharded bucket type it embeds.

Tech Stack Zero third-party dependencies — the entire implementation uses only the Go standard library: sync for locking, time for expiration arithmetic, encoding/gob for persistence, crypto/rand/math/big (with an insecurerand fallback) for the sharded cache’s hash seed, and runtime/os for the finalizer and CSPRNG-failure warning. There is no go.mod in the repository; the module is published under the legacy pre-Go-modules convention, reflected in its +incompatible version tag, and consumers import it as a plain GOPATH-style package.

Code Quality cache_test.go contains 72 test functions covering the base cache, expiration timing, NewFrom round-tripping, pointer storage, and every typed Increment*/Decrement* variant (int8 through uint64 and both float sizes), plus 19 benchmark functions comparing locked vs. sharded performance; sharded_test.go adds a further concurrency-focused test. Error handling is explicit and idiomatic — Add/Replace/typed increments return a descriptive error rather than panicking or silently no-op’ing. Naming follows standard Go exported/unexported conventions throughout. No linter configuration, formatter config, or CI workflow file is present in the repository, and there is no go.mod, so the project predates (or opted out of) modern Go tooling conventions.

API Design The public surface mirrors familiar cache semantics (Set/Get/Delete, DefaultExpiration/NoExpiration sentinels) so it reads naturally to anyone who has used Memcached-style clients. The type-assertion burden inherent to a pre-generics interface{} value store is called out directly in the README with idiomatic patterns for consumers, and the typed IncrementInt64/IncrementFloat64-style helpers exist specifically to avoid a second type assertion after an atomic update — a small but genuinely convenience-focused API decision rather than a generic wrapper.