philiprehberger-expiring_map 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: aed5fe4178a5814d949531b8352284b152a8ac520963541944584e602ebe0c17
-  data.tar.gz: 319d4b05843b15e90cb91c4487d6edc670dc3ffda54d26c9a77e09c035b4a843
+  metadata.gz: 5749cba84d6dc29c0db85c7c0112f4e8d58ae3c86b506c265d2fec2ea854c407
+  data.tar.gz: dc3f78c07157a42550dd77b156d73f6d7ffc4d24dfa4cb957cfb6f59932d88d6
 SHA512:
-  metadata.gz: a3a545614963d2b2a4db845a909ad9f2bafb0fea91b543ec9456eebf0a7ddf3a7af2029c8080f357aea6bf0294a9744b672015fbbcfc9b74942b3f524b3ab8d6
-  data.tar.gz: a7052a46245d890e339ed5e40b3bd78e21a1d29fb45441c86629ed0afaaf2fede1c69e7d77e9d401e1670d66eef55282bab0b63f4d3e7523e37473408a142ffb
+  metadata.gz: f76d3842b3da9209a8060e6fd6bf885993a158319681effd26a9a5185c67c2bf8b35cf67c28c56589aceff5e5753f05908192f3adaacda130487e36f24a13b67
+  data.tar.gz: 43f6e2b1c3e93a476f4f2cc039b7ea40685d59ab0d74a0a60eaa7983e84eced5c362c0379b1fd29d5b9086a89768db6dc523ddf042093006e1fb6211bf614006

data/CHANGELOG.md

@@ -7,6 +7,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-04-17
+
+### Added
+- `Map#fetch(key, ttl: nil) { block }` atomically memoizes the block result on miss
+
 ## [0.2.0] - 2026-04-03
 
 ### Added

data/README.md

@@ -42,6 +42,19 @@ cache.set(:config, data, ttl: 3600)   # expires in 1 hour
 cache.ttl(:token)                      # => remaining seconds
 ```
 
+### Fetch-or-compute
+
+```ruby
+cache = Philiprehberger::ExpiringMap.new(default_ttl: 300)
+
+# On miss, the block is evaluated, the result stored, and returned.
+# On hit, the stored value is returned and the block is not called.
+user = cache.fetch(:user_42) { User.find(42) }
+
+# Override the TTL for this insert only:
+token = cache.fetch(:token, ttl: 60) { Auth.issue_token }
+```
+
 ### Max Size with Eviction
 
 ```ruby
@@ -115,6 +128,7 @@ cache.select { |_k, v| v > 10 }
 | `.new(default_ttl:, max_size:)` | Create a new expiring map |
 | `#set(key, value, ttl:)` | Store a value with optional per-key TTL |
 | `#get(key)` | Retrieve a value, nil if expired or missing |
+| `#fetch(key, ttl:) { block }` | Return stored value or atomically memoize block result on miss |
 | `#set_many(hash, ttl:)` | Bulk insert from a hash |
 | `#get_many(*keys)` | Bulk get returning hash of key => value |
 | `#delete(key)` | Remove and return a value |

data/lib/philiprehberger/expiring_map/map.rb

@@ -66,6 +66,50 @@ module Philiprehberger
         end
       end
 
+      # Retrieve a value by key, or atomically compute and store it on miss
+      #
+      # If the key is present and not expired, returns the stored value.
+      # Otherwise evaluates the block, stores the result under +key+ with the
+      # default TTL (or +ttl:+ override), and returns it. The get/compute/set
+      # path runs under the same mutex used by +#get+ and +#set+ so there is
+      # no race with concurrent writers.
+      #
+      # @param key [Object] the key
+      # @param ttl [Numeric, nil] TTL in seconds for the inserted value on miss, uses default if nil
+      # @yieldreturn [Object] the value to memoize under +key+ on miss
+      # @raise [KeyError] if the key is missing/expired and no block is given
+      # @return [Object] the stored or freshly computed value
+      def fetch(key, ttl: nil)
+        @mutex.synchronize do
+          entry = @store[key]
+
+          if entry && !entry.expired?
+            @hits += 1
+            return entry.value
+          end
+
+          if entry&.expired?
+            @expirations += 1
+            fire_expire(key, entry.value)
+            @store.delete(key)
+          end
+
+          @misses += 1
+
+          raise KeyError, "key not found: #{key.inspect}" unless block_given?
+
+          value = yield
+          effective_ttl = ttl || @default_ttl
+          expires_at = Process.clock_gettime(Process::CLOCK_MONOTONIC) + effective_ttl
+
+          sweep_expired
+          evict_oldest if @max_size && @store.size >= @max_size && !@store.key?(key)
+          @store[key] = Entry.new(value, expires_at)
+
+          value
+        end
+      end
+
       # Delete a key
       #
       # @param key [Object] the key

data/lib/philiprehberger/expiring_map/version.rb

@@ -2,6 +2,6 @@
 
 module Philiprehberger
   module ExpiringMap
-    VERSION = '0.2.0'
+    VERSION = '0.3.0'
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: philiprehberger-expiring_map
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Philip Rehberger
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-04-03 00:00:00.000000000 Z
+date: 2026-04-18 00:00:00.000000000 Z
 dependencies: []
 description: A thread-safe hash map where each key has its own TTL, with automatic
   expiration, max size eviction, expiration callbacks, and Enumerable support.