philiprehberger-cache_kit 0.4.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 75ef7dbba5f362a4a3370f2e389421bca6aeb29288b42060c9f13a497070a9ba
-  data.tar.gz: caf151b0c9641bcddce86d10521b21b7746c99d2200bce020dbec3402edbdee5
+  metadata.gz: 867b798661eddfdd0c3904d4961570669cabca2ff6fb67c8a224570d86d098aa
+  data.tar.gz: c84d7c6fd9dd77522733db1ffafc3fce58248f3c41639a6729381170cbbf5bbd
 SHA512:
-  metadata.gz: 2d6e3b0e24792d38afb21da30ccdb2b453a5e68ee96ccdab24115ab3bf67158f6ee139ed1e95748ea0a31f0a23df055d8352549502af3949cf315396aacb0465
-  data.tar.gz: 5274211ebd71bac978295d49e35e80ecade8ed6696a90193761b89d2994b97c9e634858b5021d2a36b231fb34b4ee2a84f265583364793fd309be83f941a1561
+  metadata.gz: 0073bbe9674271f29c49ece552ff99bc39a26baf2f89c3d2587420b152f1e62cb844468fff3c2c3fa45b02f4f16b72a9868f608f0a46cbc8c3d6d472d27f3948
+  data.tar.gz: 4cf8b12debfbfc89ec3fd3e9150538d1fcb6de4ebbfb7e1bd2a7872ea5a74a35304497c08ef3298a2f17e64bf1772563714673f96bc4fab0c9c7b592a277b3ca

data/CHANGELOG.md

@@ -7,6 +7,28 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.6.0] - 2026-04-14
+
+### Added
+- `#ttl(key)` returns remaining seconds until expiry (nil if no TTL, missing, or expired)
+- `#expire_at(key)` returns absolute expiration `Time` (nil if no TTL, missing, or expired)
+- `#delete_many(*keys)` bulk-deletes multiple keys in a single lock acquisition; returns count removed
+- `#keys_by_tag(tag)` returns the keys associated with a tag (non-expired only)
+- `#increment(key, by: 1, ttl: nil)` atomic numeric increment with optional TTL override
+- `#decrement(key, by: 1, ttl: nil)` atomic numeric decrement
+
+### Changed
+- Align `.github/ISSUE_TEMPLATE/bug_report.yml` and `feature_request.yml` with the latest issue-template guide (required fields, field order, reproduction/proposed-api placeholders)
+
+## [0.5.0] - 2026-04-04
+
+### Changed
+- `#get_many` now accepts splat args (`get_many(*keys)`) and skips misses, returning only found entries
+
+### Added
+- `gem-version` field to bug report issue template
+- `Alternatives considered` textarea to feature request issue template
+
 ## [0.4.0] - 2026-04-01
 
 ### Added

data/README.md

@@ -83,14 +83,14 @@ 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).
+Retrieve multiple keys in a single lock acquisition. Returns a hash of found entries only, skipping misses.
 
 ```ruby
 cache.set("a", 1)
 cache.set("b", 2)
 
-cache.get_many(["a", "b", "missing"])
-# => { "a" => 1, "b" => 2, "missing" => nil }
+cache.get_many("a", "b", "missing")
+# => { "a" => 1, "b" => 2 }
 ```
 
 ### Bulk Set
@@ -169,6 +169,62 @@ cache.stats(tag: "posts")
 # => { hits: 0, misses: 0, evictions: 0 }
 ```
 
+### TTL Introspection
+
+Read the remaining or absolute expiration without consuming the entry.
+
+```ruby
+cache.set("session", "abc", ttl: 60)
+
+cache.ttl("session")       # => 59.87 (Float seconds)
+cache.expire_at("session") # => 2026-04-14 14:41:23 +0000 (Time)
+
+cache.set("permanent", "x")
+cache.ttl("permanent")     # => nil (no TTL)
+cache.ttl("missing")       # => nil
+```
+
+### Bulk Delete
+
+```ruby
+cache.set("a", 1)
+cache.set("b", 2)
+cache.set("c", 3)
+
+cache.delete_many("a", "b", "missing") # => 2 (count actually removed)
+cache.keys                              # => ["c"]
+```
+
+### Keys by Tag
+
+Inspect which keys carry a tag without invalidating them.
+
+```ruby
+cache.set("user:1", data1, tags: ["users"])
+cache.set("user:2", data2, tags: ["users"])
+cache.set("post:1", data3, tags: ["posts"])
+
+cache.keys_by_tag("users") # => ["user:1", "user:2"]
+cache.keys_by_tag(:users)  # => ["user:1", "user:2"]
+cache.keys_by_tag("none")  # => []
+```
+
+### Atomic Counters
+
+Atomically increment and decrement numeric entries. Missing or expired keys
+are initialized to 0 before the delta is applied.
+
+```ruby
+cache.increment("views")             # => 1
+cache.increment("views")             # => 2
+cache.increment("views", by: 5)      # => 7
+cache.increment("views", ttl: 3600)  # => 8 (and resets TTL to 3600s)
+
+cache.decrement("quota", by: 2)      # => -2 (if "quota" was missing)
+```
+
+Non-numeric values raise `Philiprehberger::CacheKit::Error`.
+
 ### Snapshot and Restore
 
 Serialize cache state for warm restarts. The snapshot captures all entries with their remaining TTL, tags, and LRU order.
@@ -203,12 +259,18 @@ new_cache.restore(Marshal.load(File.read("cache.bin")))
 | `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#get_many(*keys)` | Batch get, returns `{ key => value }` for found entries |
 | `#set_many(hash, ttl:, tags:)` | Bulk set multiple entries |
 | `#compact` | Prune expired entries, return eviction count |
 | `#refresh(key, ttl:)` | Reset TTL without changing value |
 | `Store#snapshot` | Serialize cache state to a hash |
 | `Store#restore(data)` | Restore cache state from a snapshot |
+| `Store#ttl(key)` | Remaining seconds until expiry (nil if none/missing/expired) |
+| `Store#expire_at(key)` | Absolute expiration `Time` (nil if none/missing/expired) |
+| `Store#delete_many(*keys)` | Bulk-delete, returns count removed |
+| `Store#keys_by_tag(tag)` | Keys associated with a tag (non-expired) |
+| `Store#increment(key, by:, ttl:)` | Atomic numeric increment |
+| `Store#decrement(key, by:, ttl:)` | Atomic numeric decrement |
 
 ## Development
 

data/lib/philiprehberger/cache_kit/batch.rb

@@ -5,14 +5,19 @@ module Philiprehberger
     # Batch operations for Store.
     module Batch
       # Retrieve multiple keys in a single lock acquisition.
+      # Returns only found (non-nil, non-expired) entries, skipping misses.
       #
       # @param keys [Array<String>] cache keys to retrieve
-      # @return [Hash] key => value pairs (missing/expired keys map to nil)
-      def get_many(keys)
+      # @return [Hash] key => value pairs for found entries only
+      def get_many(*keys)
+        keys = keys.flatten
         @mutex.synchronize do
-          keys.to_h do |key|
-            [key, fetch_entry(key)]
+          result = {}
+          keys.each do |key|
+            value = fetch_entry(key)
+            result[key] = value unless value.nil?
           end
+          result
         end
       end
     end

data/lib/philiprehberger/cache_kit/entry.rb

@@ -4,7 +4,7 @@ module Philiprehberger
   module CacheKit
     # Internal cache entry with value, TTL, and tags.
     class Entry
-      attr_reader :value, :tags, :created_at
+      attr_reader :value, :tags, :created_at, :ttl
 
       # @param value the cached value
       # @param ttl [Numeric, nil] time-to-live in seconds (nil = no expiry)
@@ -24,6 +24,26 @@ module Philiprehberger
 
         (Time.now - @created_at) >= @ttl
       end
+
+      # Absolute expiration time, or nil if the entry has no TTL.
+      #
+      # @return [Time, nil]
+      def expire_at
+        return nil if @ttl.nil?
+
+        @created_at + @ttl
+      end
+
+      # Remaining seconds until expiry. Returns nil if no TTL is set,
+      # or 0.0 if the entry has already expired.
+      #
+      # @return [Float, nil]
+      def remaining_ttl
+        return nil if @ttl.nil?
+
+        remaining = @ttl - (Time.now - @created_at)
+        remaining.positive? ? remaining : 0.0
+      end
     end
   end
 end

data/lib/philiprehberger/cache_kit/store.rb

@@ -119,8 +119,117 @@ module Philiprehberger
         end
       end
 
+      # Remaining seconds until the entry expires.
+      #
+      # Returns nil when the key is missing, expired, or has no TTL.
+      #
+      # @param key [String] the cache key
+      # @return [Float, nil]
+      def ttl(key)
+        @mutex.synchronize do
+          entry = @data[key]
+          next nil if entry.nil? || entry.expired?
+
+          entry.remaining_ttl
+        end
+      end
+
+      # Absolute expiration time of the entry.
+      #
+      # Returns nil when the key is missing, expired, or has no TTL.
+      #
+      # @param key [String] the cache key
+      # @return [Time, nil]
+      def expire_at(key)
+        @mutex.synchronize do
+          entry = @data[key]
+          next nil if entry.nil? || entry.expired?
+
+          entry.expire_at
+        end
+      end
+
+      # Bulk-delete multiple keys in a single lock acquisition.
+      # Does not fire eviction callbacks (matches #delete semantics).
+      #
+      # @param keys [Array<String>] keys to delete
+      # @return [Integer] number of keys that were actually removed
+      def delete_many(*keys)
+        keys = keys.flatten
+        @mutex.synchronize do
+          removed = 0
+          keys.each do |key|
+            next unless @data.key?(key)
+
+            remove_entry(key)
+            removed += 1
+          end
+          removed
+        end
+      end
+
+      # Return the keys associated with a given tag.
+      # Excludes expired entries.
+      #
+      # @param tag [String, Symbol]
+      # @return [Array<String>]
+      def keys_by_tag(tag)
+        tag_s = tag.to_s
+        @mutex.synchronize do
+          @data.each_with_object([]) do |(key, entry), acc|
+            next if entry.expired?
+
+            acc << key if entry.tags.include?(tag_s)
+          end
+        end
+      end
+
+      # Atomically increment a numeric entry. Initializes missing or
+      # expired keys to 0 before applying the delta.
+      #
+      # @param key [String] the cache key
+      # @param by [Numeric] amount to add (default 1)
+      # @param ttl [Numeric, nil] optional TTL override (nil preserves current TTL)
+      # @return [Numeric] the new value
+      # @raise [Error] when the existing value is not numeric
+      def increment(key, by: 1, ttl: nil)
+        @mutex.synchronize { apply_counter_delta(key, by, ttl: ttl) }
+      end
+
+      # Atomically decrement a numeric entry. See #increment.
+      #
+      # @param key [String] the cache key
+      # @param by [Numeric] amount to subtract (default 1)
+      # @param ttl [Numeric, nil] optional TTL override
+      # @return [Numeric] the new value
+      # @raise [Error] when the existing value is not numeric
+      def decrement(key, by: 1, ttl: nil)
+        @mutex.synchronize { apply_counter_delta(key, -by, ttl: ttl) }
+      end
+
       private
 
+      def apply_counter_delta(key, delta, ttl: nil)
+        entry = @data[key]
+        current, preserved_tags, preserved_ttl = counter_state(entry)
+        raise Error, "value at #{key.inspect} is not numeric" unless current.is_a?(Numeric)
+
+        new_value = current + delta
+        remove_entry(key) if @data.key?(key)
+        effective_ttl = ttl.nil? ? preserved_ttl : ttl
+        @data[key] = Entry.new(new_value, ttl: effective_ttl, tags: preserved_tags)
+        @order.push(key)
+        new_value
+      end
+
+      def counter_state(entry)
+        if entry.nil? || entry.expired?
+          [0, [], nil]
+        else
+          [entry.value, entry.tags, entry.ttl]
+        end
+      end
+
       def global_stats
         { size: @data.size, hits: @hits, misses: @misses, evictions: @evictions }
       end

data/lib/philiprehberger/cache_kit/version.rb

@@ -2,6 +2,6 @@
 
 module Philiprehberger
   module CacheKit
-    VERSION = '0.4.0'
+    VERSION = '0.6.0'
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: philiprehberger-cache_kit
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Philip Rehberger
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-04-01 00:00:00.000000000 Z
+date: 2026-04-14 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.