Add cache hit/miss statistics (hitCount, missCount, hitRate)

LruCache now tracks lifetime hit/miss counters. Every get() increments
hitCount() on a live, non-expired entry, or missCount() on an absent or
expired one. hitRate() returns hitCount / (hitCount + missCount), or 0.0
before any get() call to avoid a divide-by-zero.

Following Guava's CacheStats convention, the counters are cumulative for
the life of the cache instance and are not reset by put() or clear() -
documented in the LruCache class javadoc and the new README "Cache
Statistics" section, which also covers a new hand-calculated test that
walks a specific put/get sequence (including a capacity eviction and a
post-clear get) and asserts exact expected hit/miss/rate values.

Author: kasapdev

README.md

@@ -50,6 +50,70 @@ public class Example {
 }
 ```
 
+Another common pattern - a fixed-size cache in front of an expensive lookup, falling back on a miss:
+
+```java
+import dev.kasapdev.simplecache.LruCache;
+
+public class LookupExample {
+
+    private static final LruCache<Long, String> cache = new LruCache<>(200);
+
+    public static void main(String[] args) {
+        System.out.println(fetchUserName(42L)); // miss -> loads and caches
+        System.out.println(fetchUserName(42L)); // hit  -> served from cache
+    }
+
+    private static String fetchUserName(long userId) {
+        String cached = cache.get(userId);
+        if (cached != null) {
+            return cached;
+        }
+        String loaded = loadUserNameFromDatabase(userId); // expensive
+        cache.put(userId, loaded);
+        return loaded;
+    }
+
+    private static String loadUserNameFromDatabase(long userId) {
+        return "user-" + userId;
+    }
+}
+```
+
+## Cache Statistics
+
+Every `LruCache` tracks lifetime hit/miss counts, so you can see how effective it
+actually is in production instead of guessing:
+
+```java
+import dev.kasapdev.simplecache.LruCache;
+
+public class StatsExample {
+    public static void main(String[] args) {
+        LruCache<String, String> cache = new LruCache<>(100);
+        cache.put("user:42", "Kayra");
+
+        cache.get("user:42");   // hit
+        cache.get("user:99");   // miss (never put)
+        cache.get("user:42");   // hit
+
+        System.out.println(cache.hitCount());  // 2
+        System.out.println(cache.missCount()); // 1
+        System.out.println(cache.hitRate());   // 0.6666666666666666
+    }
+}
+```
+
+- `hitCount()` / `missCount()` are incremented by every call to `get(key)`: a hit
+  is a `get` that finds a live, non-expired entry; a miss is a `get` that finds
+  nothing (absent, or present but TTL-expired).
+- `hitRate()` is `hitCount / (hitCount + missCount)`, returning `0.0` before the
+  first `get` call rather than dividing by zero.
+- Like Guava's `CacheStats`, these counters are cumulative for the lifetime of the
+  cache instance and are **not** reset by `put` or `clear()` - they measure how
+  well the cache has been performing overall, independent of what its current
+  contents happen to be.
+
 ## API
 
 ### `LruCache<K, V>`
@@ -62,13 +126,17 @@ public class Example {
 | `void put(K key, V value)` | Inserts/updates `key` using the cache's default TTL. Evicts the least-recently-used entry if the cache is full and `key` is new. |
 | `void put(K key, V value, long ttlMillis)` | Inserts/updates `key` with an explicit TTL override for this entry only. `ttlMillis <= 0` means this entry never expires. |
 | `int size()` | Current number of entries held (including any expired-but-not-yet-evicted entries). |
-| `void clear()` | Removes all entries. |
+| `void clear()` | Removes all entries. Does not reset hit/miss statistics. |
+| `long hitCount()` | Lifetime number of `get` calls that found a live entry. |
+| `long missCount()` | Lifetime number of `get` calls that found nothing (absent or expired). |
+| `double hitRate()` | `hitCount / (hitCount + missCount)`; `0.0` if `get` has never been called. |
 
 ### Behavior notes
 
 - Eviction is genuinely LRU: both `get` and `put` on an existing key refresh that entry's recency.
 - TTL and LRU are independent: an expired entry is treated as absent by `get` even if the LRU structure hasn't evicted it yet (e.g. because the cache isn't full).
 - All public methods are safe to call concurrently from multiple threads (guarded by a single internal `ReentrantLock`).
+- Hit/miss statistics are cumulative for the life of the cache instance and are not reset by `put` or `clear()` - see [Cache Statistics](#cache-statistics).
 
 ## License
 

src/main/java/dev/kasapdev/simplecache/LruCache.java

@@ -22,6 +22,15 @@
  * <p>All public methods are safe for concurrent use from multiple threads; a
  * single {@link ReentrantLock} guards all access to the underlying map.
  *
+ * <p>The cache also tracks lifetime hit/miss statistics via {@link #hitCount()},
+ * {@link #missCount()} and {@link #hitRate()}. Every call to {@link #get(Object)}
+ * counts as either a hit (a live, non-expired entry was found) or a miss (the key
+ * was absent, or present but expired). These counters are cumulative for the life
+ * of the cache instance: like Guava's {@code CacheStats}, they measure historical
+ * hit effectiveness and are deliberately <em>not</em> reset by {@link #put(Object, Object)},
+ * {@link #put(Object, Object, long)} or {@link #clear()} - clearing the cache's
+ * contents is a different operation from resetting how well it has been performing.
+ *
  * @param <K> the type of keys maintained by this cache
  * @param <V> the type of mapped values
  */
@@ -34,6 +43,8 @@ public final class LruCache<K, V> {
     private final long defaultTtlMillis;
     private final LinkedHashMap<K, Entry<V>> map;
     private final ReentrantLock lock = new ReentrantLock();
+    private long hitCount;
+    private long missCount;
 
     /**
      * Creates a cache with the given fixed capacity and no default TTL
@@ -73,18 +84,25 @@ protected boolean removeEldestEntry(Map.Entry<K, Entry<V>> eldest) {
     /**
      * Returns the value associated with {@code key}, or {@code null} if absent
      * or expired. A successful lookup marks the entry as most-recently-used.
+     *
+     * <p>Every call counts toward this cache's hit/miss statistics: finding a
+     * live entry increments {@link #hitCount()}, while a missing or expired
+     * entry increments {@link #missCount()}.
      */
     public V get(K key) {
         lock.lock();
         try {
             Entry<V> entry = map.get(key);
             if (entry == null) {
+                missCount++;
                 return null;
             }
             if (isExpired(entry)) {
                 map.remove(key);
+                missCount++;
                 return null;
             }
+            hitCount++;
             return entry.value;
         } finally {
             lock.unlock();
@@ -127,7 +145,7 @@ public int size() {
         }
     }
 
-    /** Removes all entries from the cache. */
+    /** Removes all entries from the cache. Does not reset hit/miss statistics; see the class javadoc. */
     public void clear() {
         lock.lock();
         try {
@@ -137,6 +155,48 @@ public void clear() {
         }
     }
 
+    /**
+     * Returns the number of {@link #get(Object)} calls that found a live,
+     * non-expired entry, since this cache was created.
+     */
+    public long hitCount() {
+        lock.lock();
+        try {
+            return hitCount;
+        } finally {
+            lock.unlock();
+        }
+    }
+
+    /**
+     * Returns the number of {@link #get(Object)} calls that found no entry
+     * (absent or expired), since this cache was created.
+     */
+    public long missCount() {
+        lock.lock();
+        try {
+            return missCount;
+        } finally {
+            lock.unlock();
+        }
+    }
+
+    /**
+     * Returns the ratio of hits to total {@link #get(Object)} calls
+     * ({@code hitCount / (hitCount + missCount)}), as a value between
+     * {@code 0.0} and {@code 1.0} inclusive. Returns {@code 0.0} if
+     * {@code get} has never been called, to avoid dividing by zero.
+     */
+    public double hitRate() {
+        lock.lock();
+        try {
+            long total = hitCount + missCount;
+            return total == 0 ? 0.0 : (double) hitCount / total;
+        } finally {
+            lock.unlock();
+        }
+    }
+
     private boolean isExpired(Entry<V> entry) {
         return entry.expiresAt != NO_EXPIRY && System.currentTimeMillis() >= entry.expiresAt;
     }

src/test/java/dev/kasapdev/simplecache/LruCacheTest.java

@@ -20,9 +20,62 @@ public static void main(String[] args) throws Exception {
         testInvalidCapacityRejected();
         testSizeCountsExpiredButNotYetEvictedEntries();
         testRePuttingExistingKeyDoesNotEvictOthers();
+        testStatsAreZeroBeforeAnyGet();
+        testHitAndMissCountsWithExactExpectedValues();
         TestKit.finish();
     }
 
+    private static void testStatsAreZeroBeforeAnyGet() {
+        LruCache<String, String> cache = new LruCache<>(3);
+        TestKit.check("hitCount is 0 before any get", cache.hitCount() == 0);
+        TestKit.check("missCount is 0 before any get", cache.missCount() == 0);
+        TestKit.check("hitRate is 0.0 before any get (no divide-by-zero)", cache.hitRate() == 0.0);
+        cache.put("a", "A");
+        TestKit.check("put alone does not affect hitCount", cache.hitCount() == 0);
+        TestKit.check("put alone does not affect missCount", cache.missCount() == 0);
+    }
+
+    private static void testHitAndMissCountsWithExactExpectedValues() {
+        // Capacity 2, no TTL. Hand-tracked sequence of gets, mixing hits, misses,
+        // and a miss caused by capacity eviction.
+        LruCache<String, String> cache = new LruCache<>(2);
+        cache.put("a", "A");
+        cache.put("b", "B");
+
+        cache.get("a");        // 1: hit  (a present)                    -> hits=1 misses=0
+        cache.get("b");        // 2: hit  (b present)                    -> hits=2 misses=0
+        cache.get("missing");  // 3: miss (never put)                    -> hits=2 misses=1
+
+        // Capacity is 2 and recency order right now (oldest -> newest) is a, b
+        // (both gets above refreshed recency in that order). Inserting "c" evicts "a".
+        cache.put("c", "C");
+
+        cache.get("a");        // 4: miss (evicted by capacity)          -> hits=2 misses=2
+        cache.get("b");        // 5: hit  (survived eviction)            -> hits=3 misses=2
+        cache.get("c");        // 6: hit  (just inserted)                -> hits=4 misses=2
+        cache.get("missing");  // 7: miss (still never put)              -> hits=4 misses=3
+
+        // Overwriting an existing key is not a get, so it must not move the counters.
+        cache.put("b", "B-updated");
+        cache.get("b");        // 8: hit  (updated value, still present) -> hits=5 misses=3
+
+        TestKit.check("hitCount matches hand-calculated expected value", cache.hitCount() == 5);
+        TestKit.check("missCount matches hand-calculated expected value", cache.missCount() == 3);
+        // hitRate = hits / (hits + misses) = 5 / 8 = 0.625
+        TestKit.check("hitRate matches hand-calculated expected value", cache.hitRate() == 0.625);
+
+        // clear() must not reset lifetime stats (documented, Guava-style behavior).
+        cache.clear();
+        TestKit.check("hitCount is unchanged by clear()", cache.hitCount() == 5);
+        TestKit.check("missCount is unchanged by clear()", cache.missCount() == 3);
+        TestKit.check("hitRate is unchanged by clear()", cache.hitRate() == 0.625);
+
+        // A get() after clear() on a now-absent key is a miss, and does update stats.
+        cache.get("b");        // 9: miss (cleared)                      -> hits=5 misses=4
+        TestKit.check("missCount increments for a get() after clear()", cache.missCount() == 4);
+        TestKit.check("hitRate reflects the post-clear miss: 5 / 9", cache.hitRate() == 5.0 / 9.0);
+    }
+
     private static void testInvalidCapacityRejected() {
         boolean threwZero = false;
         try {