philiprehberger-cache_kit 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b52d4fb6a336dbcb73a7fa0ff6c2586d175f8b8562e482f06f4e45ae5a0ffc30
-  data.tar.gz: b5d3cc503b17c9946d0ee3458e42b16d59bdaf6a01adf93c173210f0828abfb3
+  metadata.gz: 12588884ddff5dd03ef08a73de323fbbdfe6c1a45c3c897d21345c3086ef2a52
+  data.tar.gz: 6379e4e269b302187fe80537570cf1df42fa189e63eb49af8fa8ca191f470fb5
 SHA512:
-  metadata.gz: dba97258e96462833062a4df553b7c9f267547fb97c79da41db696e6f4723ca0bf85cbe9215e2b674f8d8c8c89f00977bd3e7901266a7d4e8d46e6d1593420e3
-  data.tar.gz: 48625bfcb842d9eff02c0be6dd784860cfed993e3597880101dddc984d16584e00ea368a2a579de8be2eb9d1793eafe60315fe196931017e402922d17c4c8048
+  metadata.gz: 16bd7b9ff5e9db9739d744883f8cd90bd974af8dcd94be6b3bc794cff058b362a3d5028de40ad6f1ed67cc39dd1ed1b8f031e0ec233fcbbb3087b65369e1662c
+  data.tar.gz: 01c441fa9c88a967f21931aa253beeefeb39a048cbc7fcb8d455b8bc39bef62b58b7f2c7be6f191ee09fcef5ad0bf8974ca08f5c019c2d20dac7e5ba7708b42d

data/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 0.3.0
+
+### Added
+- Thread-safe `fetch` — compute-on-miss now holds the lock for the entire operation, preventing duplicate computation
+- Eviction callbacks via `on_evict { |key, value| ... }` — fires on LRU eviction and TTL expiry
+- Per-tag statistics via `stats(tag: :name)` — returns `{ hits:, misses:, evictions: }` for a specific tag
+- Batch retrieval via `get_many(keys)` — fetch multiple keys in a single lock acquisition, returns a hash
+- Snapshot and restore via `snapshot` / `restore(data)` — serialize and deserialize cache state for warm restarts
+
+## 0.2.2
+
+- Add License badge to README
+- Add bug_tracker_uri to gemspec
+
 All notable changes to this gem will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),

data/README.md

@@ -2,6 +2,7 @@
 
 [![Tests](https://github.com/philiprehberger/rb-cache-kit/actions/workflows/ci.yml/badge.svg)](https://github.com/philiprehberger/rb-cache-kit/actions/workflows/ci.yml)
 [![Gem Version](https://badge.fury.io/rb/philiprehberger-cache_kit.svg)](https://rubygems.org/gems/philiprehberger-cache_kit)
+[![License](https://img.shields.io/github/license/philiprehberger/rb-cache-kit)](LICENSE)
 
 In-memory LRU cache with TTL, tags, and thread safety for Ruby.
 
@@ -41,11 +42,13 @@ cache.set("user:1", { name: "Alice" }, ttl: 300)
 cache.get("user:1") # => { name: "Alice" }
 ```
 
-### Fetch (get or compute)
+### Fetch (compute-on-miss)
+
+Thread-safe get-or-compute. The block is only called if the key is missing or expired, and the entire operation holds the lock to prevent duplicate computation.
 
 ```ruby
 user = cache.fetch("user:1", ttl: 300) do
-  User.find(1)
+  User.find(1) # only called on cache miss
 end
 ```
 
@@ -68,6 +71,34 @@ cache.set("post:1", data3, tags: ["posts"])
 cache.invalidate_tag("users") # removes user:1 and user:2, keeps post:1
 ```
 
+### Eviction Callback
+
+Register hooks that fire when entries are evicted by LRU pressure or TTL expiry.
+
+```ruby
+cache.on_evict do |key, value|
+  logger.info("Evicted #{key}")
+end
+
+# Fires on LRU eviction
+cache.set("overflow", "data") # triggers callback if cache is full
+
+# Fires on TTL expiry (during get or prune)
+cache.prune
+```
+
+### Batch Get
+
+Retrieve multiple keys in a single lock acquisition. Returns a hash mapping each key to its value (or nil if missing/expired).
+
+```ruby
+cache.set("a", 1)
+cache.set("b", 2)
+
+cache.get_many(["a", "b", "missing"])
+# => { "a" => 1, "b" => 2, "missing" => nil }
+```
+
 ### Hash-like Access
 
 ```ruby
@@ -110,6 +141,36 @@ cache.stats
 # => { size: 1, hits: 1, misses: 1, evictions: 0 }
 ```
 
+### Stats by Tag
+
+Track per-tag hit, miss, and eviction counters.
+
+```ruby
+cache.set("user:1", data, tags: ["users"])
+cache.set("post:1", data, tags: ["posts"])
+cache.get("user:1") # hit on "users" tag
+
+cache.stats(tag: "users")
+# => { hits: 1, misses: 0, evictions: 0 }
+
+cache.stats(tag: "posts")
+# => { hits: 0, misses: 0, evictions: 0 }
+```
+
+### Snapshot and Restore
+
+Serialize cache state for warm restarts. The snapshot captures all entries with their remaining TTL, tags, and LRU order.
+
+```ruby
+# Save state before shutdown
+data = cache.snapshot
+File.write("cache.bin", Marshal.dump(data))
+
+# Restore on startup
+new_cache = Philiprehberger::CacheKit::Store.new(max_size: 500)
+new_cache.restore(Marshal.load(File.read("cache.bin")))
+```
+
 ## API
 
 | Method | Description |
@@ -117,7 +178,7 @@ cache.stats
 | `Store.new(max_size: 1000)` | Create a cache with max entries |
 | `Store#get(key)` | Get a value (nil if missing/expired) |
 | `Store#set(key, value, ttl:, tags:)` | Store a value |
-| `Store#fetch(key, ttl:, tags:, &block)` | Get or compute a value |
+| `Store#fetch(key, ttl:, tags:, &block)` | Get or compute a value (thread-safe) |
 | `Store#delete(key)` | Delete a key |
 | `Store#invalidate_tag(tag)` | Remove all entries with a tag |
 | `Store#clear` | Remove all entries |
@@ -127,7 +188,12 @@ cache.stats
 | `Store#[](key)` | Hash-like read (alias for `get`) |
 | `Store#[]=(key, value)` | Hash-like write (alias for `set` without TTL/tags) |
 | `Store#stats` | Returns `{ size:, hits:, misses:, evictions: }` |
+| `Store#stats(tag: name)` | Returns `{ hits:, misses:, evictions: }` for a tag |
 | `Store#prune` | Remove all expired entries, returns count removed |
+| `Store#on_evict { \|key, value\| }` | Register eviction callback |
+| `Store#get_many(keys)` | Batch get, returns `{ key => value }` hash |
+| `Store#snapshot` | Serialize cache state to a hash |
+| `Store#restore(data)` | Restore cache state from a snapshot |
 
 ## Development
 

data/lib/philiprehberger/cache_kit/batch.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Philiprehberger
+  module CacheKit
+    # Batch operations for Store.
+    module Batch
+      # Retrieve multiple keys in a single lock acquisition.
+      #
+      # @param keys [Array<String>] cache keys to retrieve
+      # @return [Hash] key => value pairs (missing/expired keys map to nil)
+      def get_many(keys)
+        @mutex.synchronize do
+          keys.to_h do |key|
+            [key, fetch_entry(key)]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/philiprehberger/cache_kit/callbacks.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Philiprehberger
+  module CacheKit
+    # Eviction callback support for Store.
+    module Callbacks
+      # Register a callback invoked when entries are evicted.
+      #
+      # @yield [key, value] called on eviction (LRU or TTL expiry)
+      # @return [void]
+      def on_evict(&block)
+        @mutex.synchronize { @evict_callbacks << block }
+      end
+
+      private
+
+      def init_callbacks
+        @evict_callbacks = []
+      end
+
+      def fire_evict(key, value)
+        @evict_callbacks.each { |cb| cb.call(key, value) }
+      end
+    end
+  end
+end

data/lib/philiprehberger/cache_kit/eviction.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Philiprehberger
+  module CacheKit
+    # Internal eviction and entry management for Store.
+    module Eviction
+      private
+
+      def touch(key)
+        @order.delete(key)
+        @order.push(key)
+      end
+
+      def fetch_entry(key)
+        entry = @data[key]
+        return record_miss(key) unless entry
+        return expire_and_miss(key) if entry.expired?
+
+        @hits += 1
+        record_tag_hit(entry)
+        touch(key)
+        entry.value
+      end
+
+      def record_miss(key)
+        @misses += 1
+        record_tag_miss_for(key)
+        nil
+      end
+
+      def expire_and_miss(key)
+        evict_entry(key)
+        @misses += 1
+        nil
+      end
+
+      def evict
+        oldest = @order.first
+        return unless oldest
+
+        evict_entry(oldest)
+      end
+
+      def evict_entry(key)
+        entry = @data[key]
+        return unless entry
+
+        fire_evict(key, entry.value)
+        record_tag_eviction(entry)
+        @evictions += 1
+        remove_entry(key)
+      end
+
+      def remove_entry(key)
+        @data.delete(key)
+        @order.delete(key)
+      end
+    end
+  end
+end

data/lib/philiprehberger/cache_kit/serializable.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Philiprehberger
+  module CacheKit
+    # Snapshot and restore support for Store.
+    module Serializable
+      # Serialize current cache state for persistence.
+      #
+      # @return [Hash] serialized cache data
+      def snapshot
+        @mutex.synchronize { build_snapshot }
+      end
+
+      # Restore cache state from a previous snapshot.
+      #
+      # @param data [Hash] snapshot data from #snapshot
+      # @return [void]
+      def restore(data)
+        @mutex.synchronize { apply_snapshot(data) }
+      end
+
+      private
+
+      def build_snapshot
+        entries = @data.transform_values { |e| serialize_entry(e) }
+        { entries: entries, order: @order.dup }
+      end
+
+      def serialize_entry(entry)
+        { value: entry.value, ttl: remaining_ttl(entry), tags: entry.tags }
+      end
+
+      def remaining_ttl(entry)
+        original = entry.instance_variable_get(:@ttl)
+        return nil if original.nil?
+
+        remaining = original - (Time.now - entry.created_at)
+        remaining.positive? ? remaining : 0
+      end
+
+      def apply_snapshot(data)
+        @data.clear
+        @order.clear
+        restore_entries(data[:entries])
+        @order.replace(data[:order].select { |k| @data.key?(k) })
+      end
+
+      def restore_entries(entries)
+        entries.each do |key, attrs|
+          next if attrs[:ttl]&.zero?
+
+          @data[key] = Entry.new(attrs[:value], ttl: attrs[:ttl], tags: attrs[:tags] || [])
+        end
+      end
+    end
+  end
+end

data/lib/philiprehberger/cache_kit/store.rb

@@ -4,6 +4,12 @@ module Philiprehberger
   module CacheKit
     # Thread-safe in-memory LRU cache with TTL and tag-based invalidation.
     class Store
+      include Callbacks
+      include TagStats
+      include Batch
+      include Serializable
+      include Eviction
+
       # @param max_size [Integer] maximum number of entries (LRU eviction when exceeded)
       def initialize(max_size: 1000)
         @max_size = max_size
@@ -13,151 +19,109 @@ module Philiprehberger
         @hits = 0
         @misses = 0
         @evictions = 0
+        init_callbacks
+        init_tag_stats
       end
 
       # Get a value by key. Returns nil if missing or expired.
-      #
-      # @param key [String] the cache key
-      # @return the cached value, or nil
       def get(key)
         @mutex.synchronize { fetch_entry(key) }
       end
 
-      # Store a value.
-      #
-      # @param key [String] the cache key
-      # @param value the value to cache
-      # @param ttl [Numeric, nil] time-to-live in seconds
-      # @param tags [Array<String>] tags for bulk invalidation
-      # @return the stored value
+      # Store a value with optional TTL and tags.
       def set(key, value, ttl: nil, tags: [])
-        @mutex.synchronize do
-          remove_entry(key) if @data.key?(key)
-          evict if @data.size >= @max_size
-
-          @data[key] = Entry.new(value, ttl: ttl, tags: tags)
-          @order.push(key)
-          value
-        end
-      end
-
-      # Get or compute a value.
-      #
-      # @param key [String] the cache key
-      # @param ttl [Numeric, nil] TTL for newly computed values
-      # @param tags [Array<String>] tags for newly computed values
-      # @yield computes the value if not cached
-      # @return the cached or computed value
-      def fetch(key, ttl: nil, tags: [], &block)
-        value = get(key)
-        return value unless value.nil?
+        @mutex.synchronize { store_entry(key, value, ttl: ttl, tags: tags) }
+      end
 
-        computed = block.call
-        set(key, computed, ttl: ttl, tags: tags)
-        computed
+      # Get or compute a value (thread-safe).
+      def fetch(key, ttl: nil, tags: [], &block)
+        @mutex.synchronize { fetch_or_compute(key, ttl: ttl, tags: tags, &block) }
       end
 
       # @return [Boolean] true if the key existed
       def delete(key)
-        @mutex.synchronize { @data.key?(key).tap { remove_entry(key) } }
+        @mutex.synchronize { delete_entry(key) }
       end
 
       # Invalidate all entries with a given tag.
-      #
-      # @param tag [String] the tag to invalidate
-      # @return [Integer] number of entries removed
       def invalidate_tag(tag)
-        @mutex.synchronize do
-          tag_s = tag.to_s
-          keys = @data.select { |_, entry| entry.tags.include?(tag_s) }.keys
-          keys.each { |k| remove_entry(k) }
-          keys.size
-        end
+        @mutex.synchronize { invalidate_by_tag(tag) }
       end
 
-      # @return [void]
       def clear
         @mutex.synchronize { @data.clear && @order.clear }
       end
 
-      # @return [Integer] number of entries (including expired ones not yet evicted)
       def size
         @mutex.synchronize { @data.size }
       end
 
-      # @return [Boolean] true if the key exists and is not expired
       def key?(key)
-        @mutex.synchronize do
-          entry = @data[key]
-          entry ? !entry.expired? : false
-        end
+        @mutex.synchronize { key_present?(key) }
       end
 
-      # @return [Array<String>] list of valid keys
       def keys
-        @mutex.synchronize { @data.reject { |_, entry| entry.expired? }.keys }
+        @mutex.synchronize { @data.reject { |_, e| e.expired? }.keys }
       end
 
-      # @param key [String]
       def [](key) = get(key)
 
-      # @param key [String]
-      # @param value the value to cache
       def []=(key, value)
         set(key, value)
       end
 
-      # @return [Hash] stats with :size, :hits, :misses, :evictions
-      def stats
-        @mutex.synchronize { { size: @data.size, hits: @hits, misses: @misses, evictions: @evictions } }
+      # @return [Hash] cache statistics, optionally filtered by tag
+      def stats(tag: nil)
+        @mutex.synchronize { tag ? tag_stats_for(tag) : global_stats }
       end
 
-      # @return [Integer] number of entries removed
       def prune
-        @mutex.synchronize do
-          expired_keys = @data.select { |_, entry| entry.expired? }.keys
-          expired_keys.each { |k| remove_entry(k) }
-          expired_keys.size
-        end
+        @mutex.synchronize { prune_expired }
       end
 
       private
 
-      def touch(key)
-        @order.delete(key)
-        @order.push(key)
+      def global_stats
+        { size: @data.size, hits: @hits, misses: @misses, evictions: @evictions }
       end
 
-      def fetch_entry(key)
-        entry = @data[key]
-        return record_miss unless entry
+      def store_entry(key, value, ttl: nil, tags: [])
+        remove_entry(key) if @data.key?(key)
+        evict if @data.size >= @max_size
+        @data[key] = Entry.new(value, ttl: ttl, tags: tags)
+        @order.push(key)
+        value
+      end
 
-        if entry.expired?
-          remove_entry(key)
-          return record_miss
-        end
+      def fetch_or_compute(key, ttl: nil, tags: [], &block)
+        value = fetch_entry(key)
+        return value unless value.nil?
 
-        @hits += 1
-        touch(key)
-        entry.value
+        computed = block.call
+        store_entry(key, computed, ttl: ttl, tags: tags)
+        computed
       end
 
-      def record_miss
-        @misses += 1
-        nil
+      def delete_entry(key)
+        @data.key?(key).tap { remove_entry(key) }
       end
 
-      def evict
-        oldest = @order.first
-        return unless oldest
+      def invalidate_by_tag(tag)
+        tag_s = tag.to_s
+        matched = @data.select { |_, e| e.tags.include?(tag_s) }.keys
+        matched.each { |k| remove_entry(k) }
+        matched.size
+      end
 
-        remove_entry(oldest)
-        @evictions += 1
+      def key_present?(key)
+        entry = @data[key]
+        entry ? !entry.expired? : false
       end
 
-      def remove_entry(key)
-        @data.delete(key)
-        @order.delete(key)
+      def prune_expired
+        expired = @data.select { |_, e| e.expired? }.keys
+        expired.each { |k| evict_entry(k) }
+        expired.size
       end
     end
   end

data/lib/philiprehberger/cache_kit/tag_stats.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Philiprehberger
+  module CacheKit
+    # Per-tag hit/miss/eviction tracking for Store.
+    module TagStats
+      private
+
+      def init_tag_stats
+        @tag_hits = Hash.new(0)
+        @tag_misses = Hash.new(0)
+        @tag_evictions = Hash.new(0)
+      end
+
+      def record_tag_hit(entry)
+        entry.tags.each { |t| @tag_hits[t] += 1 }
+      end
+
+      def record_tag_miss_for(key)
+        find_tags_for_key(key).each { |t| @tag_misses[t] += 1 }
+      end
+
+      def record_tag_eviction(entry)
+        entry.tags.each { |t| @tag_evictions[t] += 1 }
+      end
+
+      def find_tags_for_key(key)
+        entry = @data[key]
+        entry ? entry.tags : []
+      end
+
+      def tag_stats_for(tag)
+        tag_s = tag.to_s
+        {
+          hits: @tag_hits[tag_s],
+          misses: @tag_misses[tag_s],
+          evictions: @tag_evictions[tag_s]
+        }
+      end
+    end
+  end
+end

data/lib/philiprehberger/cache_kit/version.rb

@@ -2,6 +2,6 @@
 
 module Philiprehberger
   module CacheKit
-    VERSION = "0.2.1"
+    VERSION = "0.3.0"
   end
 end

data/lib/philiprehberger/cache_kit.rb

@@ -2,6 +2,11 @@
 
 require_relative "cache_kit/version"
 require_relative "cache_kit/entry"
+require_relative "cache_kit/callbacks"
+require_relative "cache_kit/tag_stats"
+require_relative "cache_kit/batch"
+require_relative "cache_kit/serializable"
+require_relative "cache_kit/eviction"
 require_relative "cache_kit/store"
 
 module Philiprehberger

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: philiprehberger-cache_kit
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.3.0
 platform: ruby
 authors:
 - Philip Rehberger
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-03-13 00:00:00.000000000 Z
+date: 2026-03-17 00:00:00.000000000 Z
 dependencies: []
 description: A lightweight, thread-safe in-memory LRU cache with TTL expiration and
   tag-based bulk invalidation for Ruby applications.
@@ -22,8 +22,13 @@ files:
 - LICENSE
 - README.md
 - lib/philiprehberger/cache_kit.rb
+- lib/philiprehberger/cache_kit/batch.rb
+- lib/philiprehberger/cache_kit/callbacks.rb
 - lib/philiprehberger/cache_kit/entry.rb
+- lib/philiprehberger/cache_kit/eviction.rb
+- lib/philiprehberger/cache_kit/serializable.rb
 - lib/philiprehberger/cache_kit/store.rb
+- lib/philiprehberger/cache_kit/tag_stats.rb
 - lib/philiprehberger/cache_kit/version.rb
 homepage: https://github.com/philiprehberger/rb-cache-kit
 licenses: