make terminology more consistent

Author: Thomas Stromberg

Makefile

@@ -13,11 +13,11 @@ bench:
 	go test -bench=. -benchmem
 
 # Run the 5 key benchmarks (~3-5min):
-# 1. Meta Trace Hit Rate (real-world)
-# 2. Zipf Hit Rate (synthetic)
-# 3. Single-Threaded Latency
-# 4. Zipf Throughput (1 thread)
-# 5. Zipf Throughput (16 threads)
+# 1. Single-Threaded Latency
+# 2. Zipf Throughput (1 thread)
+# 3. Zipf Throughput (16 threads)
+# 4. Meta Trace Hit Rate (real-world)
+# 5. Zipf Hit Rate (synthetic)
 benchmark:
 	@echo "=== sfcache Benchmark Suite ==="
 	@cd benchmarks && go test -run=TestBenchmarkSuite -v -timeout=300s

README.md

@@ -17,10 +17,10 @@ Designed for persistently caching API requests in an unreliable environment, thi
 - **Faster than a bat out of hell** - Best-in-class latency and throughput
 - **S3-FIFO eviction** - Better hit-rates than LRU ([learn more](https://s3fifo.com/))
 - **L2 Persistence (optional)** - Bring your own database or use built-in backends:
-  - [`persist/localfs`](persist/localfs) - Local files (gob encoding, zero dependencies)
-  - [`persist/datastore`](persist/datastore) - Google Cloud Datastore
-  - [`persist/valkey`](persist/valkey) - Valkey/Redis
-  - [`persist/cloudrun`](persist/cloudrun) - Auto-detect Cloud Run
+  - [`pkg/persist/localfs`](pkg/persist/localfs) - Local files (gob encoding, zero dependencies)
+  - [`pkg/persist/datastore`](pkg/persist/datastore) - Google Cloud Datastore
+  - [`pkg/persist/valkey`](pkg/persist/valkey) - Valkey/Redis
+  - [`pkg/persist/cloudrun`](pkg/persist/cloudrun) - Auto-detect Cloud Run
 - **Per-item TTL** - Optional expiration
 - **Graceful degradation** - Cache works even if persistence fails
 - **Zero allocation reads** - minimal GC thrashing
@@ -44,7 +44,7 @@ or with local file persistence to survive restarts:
 ```go
 import (
   "github.com/codeGROOVE-dev/sfcache"
-  "github.com/codeGROOVE-dev/sfcache/persist/localfs"
+  "github.com/codeGROOVE-dev/sfcache/pkg/persist/localfs"
 )
 
 p, _ := localfs.New[string, User]("myapp", "")
@@ -57,6 +57,8 @@ cache.Store.Len(ctx)                  // Access persistence layer directly
 A persistent cache suitable for Cloud Run or local development; uses Cloud Datastore if available
 
 ```go
+import "github.com/codeGROOVE-dev/sfcache/pkg/persist/cloudrun"
+
 p, _ := cloudrun.New[string, User](ctx, "myapp")
 cache, _ := sfcache.Persistent[string, User](ctx, p)
 ```
@@ -68,36 +70,6 @@ sfcache prioritizes high hit-rates and low read latency, but it performs quite w
 Here's the results from an M4 MacBook Pro - run `make bench` to see the results for yourself:
 
 ```
->>> TestMetaTrace: Meta Trace Hit Rate (10M ops) (go test -run=TestMetaTrace -v)
-
-### Meta Trace Hit Rate (10M ops from Meta KVCache)
-
-| Cache         | 50K cache | 100K cache |
-|---------------|-----------|------------|
-| sfcache       |   68.19%  |   76.03%   |
-| otter         |   41.31%  |   55.41%   |
-| ristretto     |   40.33%  |   48.91%   |
-| tinylfu       |   53.70%  |   54.79%   |
-| freecache     |   56.86%  |   65.52%   |
-| lru           |   65.21%  |   74.22%   |
-
-- 🔥 Meta trace: 2.4% better than next best (lru)
-
->>> TestHitRate: Zipf Hit Rate (go test -run=TestHitRate -v)
-
-### Hit Rate (Zipf alpha=0.99, 1M ops, 1M keyspace)
-
-| Cache         | Size=1% | Size=2.5% | Size=5% |
-|---------------|---------|-----------|---------|
-| sfcache       |  64.19% |    69.23% |  72.50% |
-| otter         |  61.64% |    67.94% |  71.38% |
-| ristretto     |  34.88% |    41.25% |  46.62% |
-| tinylfu       |  63.83% |    68.25% |  71.56% |
-| freecache     |  56.65% |    57.75% |  63.39% |
-| lru           |  57.33% |    64.55% |  69.92% |
-
-- 🔥 Hit rate: 1.1% better than next best (tinylfu)
-
 >>> TestLatency: Single-Threaded Latency (go test -run=TestLatency -v)
 
 ### Single-Threaded Latency (sorted by Get)
@@ -143,6 +115,36 @@ Here's the results from an M4 MacBook Pro - run `make bench` to see the results
 | tinylfu       |    4.25M   |
 
 - 🔥 Throughput: 187% faster than next best (freecache)
+
+>>> TestMetaTrace: Meta Trace Hit Rate (10M ops) (go test -run=TestMetaTrace -v)
+
+### Meta Trace Hit Rate (10M ops from Meta KVCache)
+
+| Cache         | 50K cache | 100K cache |
+|---------------|-----------|------------|
+| sfcache       |   68.19%  |   76.03%   |
+| otter         |   41.31%  |   55.41%   |
+| ristretto     |   40.33%  |   48.91%   |
+| tinylfu       |   53.70%  |   54.79%   |
+| freecache     |   56.86%  |   65.52%   |
+| lru           |   65.21%  |   74.22%   |
+
+- 🔥 Meta trace: 2.4% better than next best (lru)
+
+>>> TestHitRate: Zipf Hit Rate (go test -run=TestHitRate -v)
+
+### Hit Rate (Zipf alpha=0.99, 1M ops, 1M keyspace)
+
+| Cache         | Size=1% | Size=2.5% | Size=5% |
+|---------------|---------|-----------|---------|
+| sfcache       |  64.19% |    69.23% |  72.50% |
+| otter         |  61.64% |    67.94% |  71.38% |
+| ristretto     |  34.88% |    41.25% |  46.62% |
+| tinylfu       |  63.83% |    68.25% |  71.56% |
+| freecache     |  56.65% |    57.75% |  63.39% |
+| lru           |  57.33% |    64.55% |  69.92% |
+
+- 🔥 Hit rate: 1.1% better than next best (tinylfu)
 ```
 
 Cache performance is a game of balancing trade-offs. There will be workloads where other cache implementations are better, but nobody blends speed and persistence like we do.

benchmarks/benchmark_test.go

@@ -35,25 +35,25 @@ func TestBenchmarkSuite(t *testing.T) {
 	fmt.Println("sfcache benchmark bake-off")
 	fmt.Println()
 
-	// 1. Real-world hit rate from Meta KVCache production trace
-	printTestHeader("TestMetaTrace", "Meta Trace Hit Rate (10M ops)")
-	runMetaTraceHitRate()
-
-	// 2. Synthetic hit rate with Zipf distribution
-	printTestHeader("TestHitRate", "Zipf Hit Rate")
-	runHitRateBenchmark()
-
-	// 3. Single-threaded latency
+	// 1. Single-threaded latency
 	printTestHeader("TestLatency", "Single-Threaded Latency")
 	runPerformanceBenchmark()
 
-	// 4. Single-threaded throughput (Zipf)
+	// 2. Single-threaded throughput (Zipf)
 	printTestHeader("TestZipfThroughput1", "Zipf Throughput (1 thread)")
 	runZipfThroughputBenchmark(1)
 
-	// 5. Multi-threaded throughput (Zipf)
+	// 3. Multi-threaded throughput (Zipf)
 	printTestHeader("TestZipfThroughput16", "Zipf Throughput (16 threads)")
 	runZipfThroughputBenchmark(16)
+
+	// 4. Real-world hit rate from Meta KVCache production trace
+	printTestHeader("TestMetaTrace", "Meta Trace Hit Rate (10M ops)")
+	runMetaTraceHitRate()
+
+	// 5. Synthetic hit rate with Zipf distribution
+	printTestHeader("TestHitRate", "Zipf Hit Rate")
+	runHitRateBenchmark()
 }
 
 func printTestHeader(testName, description string) {

memory.go

@@ -40,7 +40,7 @@ func Memory[K comparable, V any](opts ...Option) *MemoryCache[K, V] {
 // Get retrieves a value from the cache.
 // Returns the value and true if found, or the zero value and false if not found.
 func (c *MemoryCache[K, V]) Get(key K) (V, bool) {
-	return c.memory.getFromMemory(key)
+	return c.memory.get(key)
 }
 
 // GetOrSet retrieves a value from the cache, or computes and stores it if not found.
@@ -49,7 +49,7 @@ func (c *MemoryCache[K, V]) Get(key K) (V, bool) {
 // This is optimized to perform a single shard lookup and lock acquisition.
 func (c *MemoryCache[K, V]) GetOrSet(key K, loader func() V, ttl ...time.Duration) V {
 	// We can't use the optimized path with a loader since we'd hold the lock during loader()
-	if val, ok := c.memory.getFromMemory(key); ok {
+	if val, ok := c.memory.get(key); ok {
 		return val
 	}
 	val := loader()
@@ -65,34 +65,34 @@ func (c *MemoryCache[K, V]) SetIfAbsent(key K, value V, ttl ...time.Duration) (V
 	if len(ttl) > 0 {
 		t = ttl[0]
 	}
-	return c.memory.getOrSetMemory(key, value, timeToNano(c.expiry(t)))
+	return c.memory.getOrSet(key, value, timeToNano(c.expiry(t)))
 }
 
 // Set stores a value in the cache.
 // If no TTL is provided, the default TTL is used.
-// If no default TTL is configured, the item never expires.
+// If no default TTL is configured, the entry never expires.
 func (c *MemoryCache[K, V]) Set(key K, value V, ttl ...time.Duration) {
 	var t time.Duration
 	if len(ttl) > 0 {
 		t = ttl[0]
 	}
-	c.memory.setToMemory(key, value, timeToNano(c.expiry(t)))
+	c.memory.set(key, value, timeToNano(c.expiry(t)))
 }
 
 // Delete removes a value from the cache.
 func (c *MemoryCache[K, V]) Delete(key K) {
-	c.memory.deleteFromMemory(key)
+	c.memory.del(key)
 }
 
-// Len returns the number of items in the cache.
+// Len returns the number of entries in the cache.
 func (c *MemoryCache[K, V]) Len() int {
-	return c.memory.memoryLen()
+	return c.memory.len()
 }
 
 // Flush removes all entries from the cache.
 // Returns the number of entries removed.
 func (c *MemoryCache[K, V]) Flush() int {
-	return c.memory.flushMemory()
+	return c.memory.flush()
 }
 
 // Close releases resources held by the cache.
@@ -132,7 +132,7 @@ func defaultConfig() *config {
 // Option configures a MemoryCache or PersistentCache.
 type Option func(*config)
 
-// WithSize sets the maximum number of items in the memory cache.
+// WithSize sets the maximum number of entries in the memory cache.
 func WithSize(n int) Option {
 	return func(c *config) {
 		c.size = n
@@ -155,8 +155,8 @@ func WithGhostRatio(r float64) Option {
 	}
 }
 
-// WithTTL sets the default TTL for cache items.
-// Items without an explicit TTL will use this value.
+// WithTTL sets the default TTL for cache entries.
+// Entries without an explicit TTL will use this value.
 func WithTTL(d time.Duration) Option {
 	return func(c *config) {
 		c.defaultTTL = d

persistent.go

@@ -17,7 +17,7 @@ type PersistentCache[K comparable, V any] struct {
 	//   cache.Store.Len(ctx)
 	//   cache.Store.Flush(ctx)
 	//   cache.Store.Cleanup(ctx, maxAge)
-	Store persist.Layer[K, V]
+	Store persist.Store[K, V]
 
 	memory     *s3fifo[K, V]
 	defaultTTL time.Duration
@@ -43,7 +43,7 @@ type PersistentCache[K comparable, V any] struct {
 //	cache.Set(ctx, "user:123", user, time.Hour)   // explicit TTL
 //	user, ok, err := cache.Get(ctx, "user:123")
 //	storeCount, _ := cache.Store.Len(ctx)
-func Persistent[K comparable, V any](ctx context.Context, p persist.Layer[K, V], opts ...Option) (*PersistentCache[K, V], error) {
+func Persistent[K comparable, V any](ctx context.Context, p persist.Store[K, V], opts ...Option) (*PersistentCache[K, V], error) {
 	cfg := defaultConfig()
 	for _, opt := range opts {
 		opt(cfg)
@@ -77,7 +77,7 @@ func (c *PersistentCache[K, V]) doWarmup(ctx context.Context) {
 	entryCh, errCh := c.Store.LoadRecent(ctx, c.warmup)
 
 	for entry := range entryCh {
-		c.memory.setToMemory(entry.Key, entry.Value, timeToNano(entry.Expiry))
+		c.memory.set(entry.Key, entry.Value, timeToNano(entry.Expiry))
 	}
 
 	// Drain error channel (errors silently ignored for best-effort warmup)
@@ -90,7 +90,7 @@ func (c *PersistentCache[K, V]) doWarmup(ctx context.Context) {
 //nolint:gocritic // unnamedResult - public API signature is intentionally clear without named returns
 func (c *PersistentCache[K, V]) Get(ctx context.Context, key K) (V, bool, error) {
 	// Check memory first
-	if val, ok := c.memory.getFromMemory(key); ok {
+	if val, ok := c.memory.get(key); ok {
 		return val, true, nil
 	}
 
@@ -102,7 +102,7 @@ func (c *PersistentCache[K, V]) Get(ctx context.Context, key K) (V, bool, error)
 	}
 
 	// Check persistence
-	val, expiry, found, err := c.Store.Load(ctx, key)
+	val, expiry, found, err := c.Store.Get(ctx, key)
 	if err != nil {
 		return zero, false, fmt.Errorf("persistence load: %w", err)
 	}
@@ -112,7 +112,7 @@ func (c *PersistentCache[K, V]) Get(ctx context.Context, key K) (V, bool, error)
 	}
 
 	// Add to memory cache for future hits
-	c.memory.setToMemory(key, val, timeToNano(expiry))
+	c.memory.set(key, val, timeToNano(expiry))
 
 	return val, true, nil
 }
@@ -171,10 +171,10 @@ func (c *PersistentCache[K, V]) Set(ctx context.Context, key K, value V, ttl ...
 	}
 
 	// ALWAYS update memory first - reliability guarantee
-	c.memory.setToMemory(key, value, timeToNano(expiry))
+	c.memory.set(key, value, timeToNano(expiry))
 
 	// Update persistence
-	if err := c.Store.Store(ctx, key, value, expiry); err != nil {
+	if err := c.Store.Set(ctx, key, value, expiry); err != nil {
 		return fmt.Errorf("persistence store failed: %w", err)
 	}
 
@@ -199,14 +199,14 @@ func (c *PersistentCache[K, V]) SetAsync(ctx context.Context, key K, value V, tt
 	}
 
 	// ALWAYS update memory first - reliability guarantee (synchronous)
-	c.memory.setToMemory(key, value, timeToNano(expiry))
+	c.memory.set(key, value, timeToNano(expiry))
 
 	// Update persistence asynchronously (fire-and-forget)
 	//nolint:contextcheck // Intentionally detached - persistence should complete even if caller cancels
 	go func() {
 		storeCtx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
 		defer cancel()
-		if err := c.Store.Store(storeCtx, key, value, expiry); err != nil {
+		if err := c.Store.Set(storeCtx, key, value, expiry); err != nil {
 			slog.Error("async persistence failed", "key", key, "error", err)
 		}
 	}()
@@ -218,7 +218,7 @@ func (c *PersistentCache[K, V]) SetAsync(ctx context.Context, key K, value V, tt
 // The value is always removed from memory. Returns an error if persistence deletion fails.
 func (c *PersistentCache[K, V]) Delete(ctx context.Context, key K) error {
 	// Remove from memory first (always succeeds)
-	c.memory.deleteFromMemory(key)
+	c.memory.del(key)
 
 	// Validate key before accessing persistence (security: prevent path traversal)
 	if err := c.Store.ValidateKey(key); err != nil {
@@ -235,7 +235,7 @@ func (c *PersistentCache[K, V]) Delete(ctx context.Context, key K) error {
 // Flush removes all entries from the cache, including persistent storage.
 // Returns the total number of entries removed from memory and persistence.
 func (c *PersistentCache[K, V]) Flush(ctx context.Context) (int, error) {
-	memoryRemoved := c.memory.flushMemory()
+	memoryRemoved := c.memory.flush()
 
 	persistRemoved, err := c.Store.Flush(ctx)
 	if err != nil {
@@ -245,10 +245,10 @@ func (c *PersistentCache[K, V]) Flush(ctx context.Context) (int, error) {
 	return memoryRemoved + persistRemoved, nil
 }
 
-// Len returns the number of items in the memory cache.
-// For persistence item count, use cache.Store.Len(ctx).
+// Len returns the number of entries in the memory cache.
+// For persistence entry count, use cache.Store.Len(ctx).
 func (c *PersistentCache[K, V]) Len() int {
-	return c.memory.memoryLen()
+	return c.memory.len()
 }
 
 // Close releases resources held by the cache.