philiprehberger-expiring_map 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5749cba84d6dc29c0db85c7c0112f4e8d58ae3c86b506c265d2fec2ea854c407
-  data.tar.gz: dc3f78c07157a42550dd77b156d73f6d7ffc4d24dfa4cb957cfb6f59932d88d6
+  metadata.gz: c9113519082c9f4bc5b232176d347f5bf07ffd282a63f27be15a68443a6aee90
+  data.tar.gz: 7b90b98bab68612c39f4723c4d7673a1149155c50531972754eb7ae0daea841c
 SHA512:
-  metadata.gz: f76d3842b3da9209a8060e6fd6bf885993a158319681effd26a9a5185c67c2bf8b35cf67c28c56589aceff5e5753f05908192f3adaacda130487e36f24a13b67
-  data.tar.gz: 43f6e2b1c3e93a476f4f2cc039b7ea40685d59ab0d74a0a60eaa7983e84eced5c362c0379b1fd29d5b9086a89768db6dc523ddf042093006e1fb6211bf614006
+  metadata.gz: f55f4d5d64f2b81cd57519784e8fdce758360f72c9cd85c6789f29bea0950de80eaf3a649b1d0c070c890179db3a126893e9933aa39f9e41817fcccc765c3e34
+  data.tar.gz: 40c275b4ef7abd9dfc531bcf6ef19e44d812e25b1eb5158c4d4b2cdea07f6e0952dff5e6543a6fad9cb67ea4d2a6389dfbda2c6c2ce4dee867173d86f374fb44

data/CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-04-27
+
+### Added
+- `Map#purge_expired!` — actively sweep expired entries and return the count removed; fires `on_expire` callbacks. Useful for explicit cleanup in long-running processes that read sparingly.
+- `Map#expired?(key)` — predicate for whether an entry is present-but-expired without deleting it or firing `on_expire`. Distinct from `get(key).nil?`, which can't tell "missing" from "expired".
+
 ## [0.3.0] - 2026-04-17
 
 ### Added

data/README.md

@@ -121,6 +121,33 @@ cache.each { |key, value| puts "#{key}: #{value}" }
 cache.select { |_k, v| v > 10 }
 ```
 
+### Manual Sweep
+
+Most read methods (`get`, `size`, `each`, `keys`, `values`) sweep expired
+entries lazily on access. Long-running processes that read sparingly can
+accumulate stale entries between reads — call `purge_expired!` to reclaim
+memory and fire `on_expire` callbacks for everything that has expired:
+
+```ruby
+cache.set(:a, 1, ttl: 0.01)
+cache.set(:b, 2, ttl: 10)
+sleep 0.02
+
+cache.purge_expired!  # => 1   (number of entries removed)
+cache.keys             # => [:b]
+```
+
+`expired?(key)` returns whether a present key has elapsed its TTL — without
+deleting the entry or firing `on_expire`. Distinct from `get(key).nil?`,
+which can't tell "missing" from "expired":
+
+```ruby
+cache.set(:dead, 'gone', ttl: 0.01)
+sleep 0.02
+cache.expired?(:dead)   # => true
+cache.expired?(:nope)   # => false (missing, not expired)
+```
+
 ## API
 
 | Method | Description |
@@ -142,6 +169,8 @@ cache.select { |_k, v| v > 10 }
 | `#on_expire { \|k, v\| }` | Register expiration callback |
 | `#clear` | Remove all entries |
 | `#each { \|k, v\| }` | Iterate over non-expired entries |
+| `#purge_expired!` | Actively sweep expired entries; fires `on_expire`; returns the count removed |
+| `#expired?(key)` | Whether the entry at `key` is present-but-expired (does not delete or fire `on_expire`) |
 
 ## Development
 

data/lib/philiprehberger/expiring_map/map.rb

@@ -268,6 +268,39 @@ module Philiprehberger
         end
       end
 
+      # Actively sweep expired entries and return how many were removed.
+      #
+      # Most read methods (`get`, `size`, `each`, `keys`, `values`) sweep lazily,
+      # so long-running processes that read sparingly may accumulate stale
+      # entries before the next read triggers cleanup. Call this to reclaim
+      # memory and fire `on_expire` callbacks for everything that has expired.
+      #
+      # @return [Integer] number of entries removed
+      def purge_expired!
+        @mutex.synchronize do
+          before = @store.size
+          sweep_expired
+          before - @store.size
+        end
+      end
+
+      # Whether the entry at +key+ has expired.
+      #
+      # Returns +false+ when the key is missing or still valid; returns +true+
+      # when the entry exists but its TTL has elapsed. Unlike `get`, this does
+      # not delete the entry or fire `on_expire`.
+      #
+      # @param key [Object] the key
+      # @return [Boolean]
+      def expired?(key)
+        @mutex.synchronize do
+          entry = @store[key]
+          return false unless entry
+
+          entry.expired?
+        end
+      end
+
       private
 
       # Remove all expired entries, firing callbacks

data/lib/philiprehberger/expiring_map/version.rb

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

metadata

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