safe_memoize 0.7.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 41e3b8e3232ef52d536166c4e701a99a8d7a1e86e2c6d07493d1838d904dbef6
-  data.tar.gz: dac922ad348d3ccf14d8946035b5a0e7709cacc899dcc6e0713da77c980ac6ca
+  metadata.gz: 0b47b6031a8f395991376eec0407b93d1cf02caecad23f4d77e4d68234ef87b5
+  data.tar.gz: 7542678912a0a39425a75e3addfc718f2abb35068e28e0cdc0444c294dd4c4c1
 SHA512:
-  metadata.gz: a7f263ac2b16ff248ccf6afa158aaaae5a7fd69cadef68ff6926c3d96257378df8d4295f2eac8278a68de12492128282c1ffea42da95c178de7e5619981c8634
-  data.tar.gz: b50610d8ac36d0c7ff4fe9ed174a7f7864654f4178bc5778a9555eda1d934320b7ee0bcf4de53919e9dfacc35d06d8320f0b9dc8e8a25d6fab6808dfb0c0aab4
+  metadata.gz: a304040bf86b1bc359c91f3d687a9f45e020bdaddded53b82a87e473553491aa9daba1ac45f8abadffb8ede8af270479f73762ab47357486aef9b46043afacde
+  data.tar.gz: 79d6a552f98f9f2ef1482832c211cc7b0a58f6481c989320c19db63b870a1723b482304955a133c661a0082a07c17de539258a9f869da0b5cbd0aaa2acacd96a

data/.github/workflows/ci.yml

@@ -10,7 +10,27 @@ on:
 permissions:
   contents: read
 
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
+
 jobs:
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v5
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "3.4"
+          bundler-cache: true
+
+      - name: Run StandardRB
+        run: bundle exec standardrb
+
   test:
     name: Ruby ${{ matrix.ruby }}
     runs-on: ubuntu-latest
@@ -32,6 +52,13 @@ jobs:
           ruby-version: ${{ matrix.ruby }}
           bundler-cache: true
 
-      - name: Run test and lint suite
-        run: bundle exec rake
+      - name: Run test suite
+        run: bundle exec rspec
+
+      - name: Upload coverage to Codecov
+        uses: codecov/codecov-action@v5
+        if: matrix.ruby == '3.4'
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          files: coverage/.resultset.json
 

data/.github/workflows/release.yml

@@ -7,6 +7,7 @@ on:
 
 permissions:
   contents: write
+  id-token: write
 
 jobs:
   release:
@@ -66,10 +67,13 @@ jobs:
           RELEASE_TAG: ${{ github.ref_name }}
         run: echo "RubyGems already has version ${RELEASE_TAG#v}; skipping gem push."
 
+      - name: Configure RubyGems credentials (trusted publishing)
+        if: steps.rubygems.outputs.already_published != 'true'
+        uses: rubygems/configure-rubygems-credentials@v1.0.0
+
       - name: Publish gem to RubyGems
         if: steps.rubygems.outputs.already_published != 'true'
         env:
-          GEM_HOST_API_KEY: ${{ secrets.RUBYGEMS_API_KEY }}
           RELEASE_TAG: ${{ github.ref_name }}
         run: |
           version="${RELEASE_TAG#v}"

data/CHANGELOG.md

@@ -1,139 +1,158 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html)
+from v1.0.0 onwards. Prior 0.x releases may include breaking changes between minor versions.
+
 ## [Unreleased]
 
+## [0.9.0] - 2026-05-22
+
+### Added
+
+- `ActiveSupport::Notifications` integration — opt-in via `SafeMemoize.configure { |c| c.active_support_notifications = true }`; emits `cache_hit.safe_memoize`, `cache_miss.safe_memoize`, `cache_evict.safe_memoize`, `cache_expire.safe_memoize`, and `cache_store.safe_memoize` events; each payload includes `:method`, `:key`, and `:class`; zero overhead when ActiveSupport is not loaded
+- `SafeMemoize::Adapters::StatsD` — thin optional adapter that routes lifecycle events to any StatsD client via `SafeMemoize.configure { |c| c.statsd_client = my_client }`; emits `safe_memoize.hit`, `safe_memoize.miss`, `safe_memoize.evict`, `safe_memoize.expire`, and `safe_memoize.store` with `method:` and `class:` tags; client errors are rescued and warned rather than raised
+- Formal benchmark suite (`benchmarks/benchmark.rb`) — six scenarios covering zero-arg cache hit/miss, with-argument hit, fast vs locked path, shared vs instance cache, and concurrent throughput under 8-thread contention; optional comparisons against `memery` and `memo_wise`; run with `bundle exec ruby benchmarks/benchmark.rb`
+- Concurrency stress test suite (`spec/concurrency_spec.rb`) — 18 barrier-synchronized examples hammering the fast path, locked path, and shared cache under 30 concurrent threads; covers exactly-once computation, LRU size invariant, hook count integrity, metric accuracy, TTL pruning, and deadlock detection (10-second timeout per run)
+- `SafeMemoize::Adapters::OpenTelemetry` — optional adapter that wraps each cache-miss computation in an OpenTelemetry span; configure via `SafeMemoize.configure { |c| c.opentelemetry_tracer = OpenTelemetry.tracer_provider.tracer("safe_memoize") }`; span name is `"safe_memoize.compute"` with attributes `safe_memoize.method`, `safe_memoize.class`, and `safe_memoize.cache_hit`; falls back to untraced execution when the tracer is absent or does not respond to `in_span`
+- `SafeMemoize::Rails` — opt-in request-scope helpers (`require "safe_memoize/rails"`): `SafeMemoize::Rails::RequestScoped` concern auto-registers `after_action :reset_all_memos` in controllers and exposes `reset_request_memos` elsewhere; `SafeMemoize::Rails::Middleware` Rack middleware resets all thread-tracked instances (`SafeMemoize::Rails.track(self)`) at the end of each request even on error
+
+## [0.8.0] - 2026-05-21
+
+### Added
+
+- Raise `ArgumentError` at definition time when `memoize` is called on a method that does not exist on the class — previously the error only surfaced at runtime when `super` had nothing to call
+- Key serialization safety: argument arrays, hashes, and strings are deep-frozen into an independent copy when the cache key is built, so callers that mutate their arguments after a call can no longer corrupt or miss the cached entry
+- `memo_inspect` — single-entry deep-inspection helper returning all metadata for one cached call in one mutex-held read: `cached`, `value`, `hits`, `misses`, `ttl_remaining`, `age`, `custom_key`, and `lru_position`; returns `nil` when the entry is not cached
+- Deprecation infrastructure: `SafeMemoize.deprecate(subject, message:, horizon:)` emits a structured `[SafeMemoize]` warning to stderr by default; configurable via `SafeMemoize.configure { |c| c.on_deprecation = ->(msg) { ... } }` to raise, log, or collect warnings
+- `memoize_all only:` — symmetric counterpart to `except:`; explicitly lists the methods to memoize and skips all others; raises `ArgumentError` when both `only:` and `except:` are given
+- Hook error isolation: exceptions raised inside lifecycle hooks no longer propagate to the caller; by default a `[SafeMemoize] Hook error in <type>: <message>` warning is emitted to stderr; configurable via `SafeMemoize.configure { |c| c.on_hook_error = ->(error, hook_type, cache_key) { ... } }` to raise, log, or silence
+
 ## [0.7.0] - 2026-05-18
 
-- Add `memo_preload` to batch-warm multiple cache entries in one call
-  - `obj.memo_preload(:find, [1], [2], [3])` calls the memoized method for each arg set and caches all results
-  - Returns an array of results in the same order as the input arg sets
-  - Computes each entry only once — subsequent calls return from cache
-- Add `on_memo_store` hook that fires whenever a value is written to the cache
-  - Fires on every cache miss (fast path and LRU path)
-  - Also fires when entries are written via `warm_memo` or `load_memo`
-  - Does not fire on cache hits or when a conditional `:if`/`:unless` prevents storing
-  - Fires on the calling instance for `shared: true` misses
-  - Completes the full lifecycle hook set: `on_store`, `on_hit`, `on_miss`, `on_expire`, `on_evict`
-- Add per-method `cache_metrics_reset(:method)` to clear stats for a single method without wiping the rest
-  - `cache_metrics_reset` (no args) still clears all metrics as before
-- Add `SafeMemoize.configure` for global default options
-  - `SafeMemoize.configure { |c| c.default_ttl = 60 }` applies a TTL to all subsequently memoized methods
-  - `SafeMemoize.configure { |c| c.default_max_size = 100 }` sets a global LRU size limit
-  - Per-call options (`ttl:`, `max_size:`) override the global defaults
-  - `SafeMemoize.reset_configuration!` restores defaults to `nil`
-- Add `memo_touch` to reset the expiry clock on a cached entry without recomputing
-  - `memo_touch(:method, *args)` extends the entry's TTL from now using the original TTL window
-  - `memo_touch(:method, *args, ttl: 30)` sets a new TTL explicitly
-  - Returns `true` on success, `false` if the entry is not cached or already expired
-- Add `shared_memo_age` class method to inspect how long ago a shared entry was cached
-- Add `shared_memo_stale?` class method to check whether a shared entry's TTL has elapsed
-- Update RBS type signatures for all new methods and the `Configuration` class
-- Add `key:` option to `memoize` for class-level cache key generation
-  - `memoize :method, key: ->(a, b) { a }` defines a key generator at the class level — calls whose key block returns the same value share one cache entry
-  - Instance-level `memoize_with_custom_key` still takes priority over `key:`
-  - Composes with all existing options (`ttl:`, `max_size:`, `shared:`, `if:`, etc.)
-  - Raises `ArgumentError` if `key:` is not callable
-- Add `shared:` support to `memoize_all` (was already functional via `**options` passthrough; now tested and documented)
-- Add `memo_refresh` to force-recompute a cached entry and store the new value in one call
-- Add `memo_age` to return how many seconds ago an entry was cached (`nil` if not cached or expired)
-- Add `memo_stale?` to check whether a cached entry exists but its TTL has elapsed
+### Added
+
+- `memo_preload` to batch-warm multiple cache entries in one call — `obj.memo_preload(:find, [1], [2], [3])` calls the memoized method for each arg set, caches all results, and returns them in input order
+- `on_memo_store` hook that fires whenever a value is written to the cache (miss, `warm_memo`, or `load_memo`); completes the full lifecycle hook set alongside `on_hit`, `on_miss`, `on_expire`, and `on_evict`
+- `SafeMemoize.configure` for global default options — `default_ttl` and `default_max_size` apply to all subsequently memoized methods; per-call options override the global defaults
+- `SafeMemoize.reset_configuration!` to restore all global defaults to `nil`
+- `memo_touch` to reset the expiry clock on a cached entry without recomputing — accepts an optional `ttl:` override; returns `true` on success, `false` if the entry is not cached or already expired
+- `shared_memo_age` class method to inspect how long ago a shared entry was cached
+- `shared_memo_stale?` class method to check whether a shared entry's TTL has elapsed
+- `key:` option on `memoize` for class-level cache key generation — calls whose key block returns the same value share one cache entry; instance-level `memoize_with_custom_key` still takes priority
+- `memo_refresh` to force-recompute a cached entry and store the new value in one call
+- `memo_age` to return how many seconds ago an entry was cached (`nil` if not cached or expired)
+- `memo_stale?` to check whether a cached entry exists but its TTL has elapsed
+
+### Changed
+
+- `cache_metrics_reset` now accepts an optional method name to clear stats for a single method only; calling without arguments still clears all metrics
+- `shared:` support in `memoize_all` is now tested and documented (was already functional via `**options` passthrough)
+- RBS type signatures updated for all new methods and the `Configuration` class
 
 ## [0.6.3] - 2026-05-18
 
+### Changed
+
 - Upgrade `softprops/action-gh-release` from v2 to v3 to resolve Node.js 20 deprecation warning in release workflow
 
 ## [0.6.2] - 2026-05-18
 
-- Achieve 100% line coverage across all lib files
-  - Add SimpleCov filter to exclude `/spec` from coverage reporting
-  - Add tests for `memo_ttl` in `CacheRecordMethods` covering nil, valid numeric, negative, and non-numeric inputs
-  - Add tests for private `memo_cache_read` in `CacheStoreMethods` covering nil cache, live hit, and expired entry
-  - Add tests for `memo_keys` / `memo_values` with custom-key entries, covering the `custom_key:` projection branch in `InspectionMethods`
-  - Add missing error-case tests for `ReleaseTooling.update_version_file` (no VERSION constant) and `finalize_changelog` (no Unreleased heading)
+### Added
+
+- 100% line coverage across all lib files — added tests for edge cases in `CacheRecordMethods`, `CacheStoreMethods`, `InspectionMethods`, and `ReleaseTooling`; added SimpleCov filter to exclude `/spec` from coverage reporting
 
 ## [0.6.1] - 2026-05-17
 
-- Fix `memo_keys` and `memo_values` showing `args: custom_key, kwargs: nil` for methods using `memoize_with_custom_key` — now surfaces as `custom_key:`
-- Refactor `cache_stats` / `cache_stats_for` to share aggregation logic via private helpers
+### Changed
+
+- Refactored `cache_stats` / `cache_stats_for` to share aggregation logic via private helpers
+
+### Fixed
+
+- `memo_keys` and `memo_values` showed `args: custom_key, kwargs: nil` for methods using `memoize_with_custom_key` — now correctly surfaces as `custom_key:`
 
 ## [0.6.0] - 2026-05-17
 
-- Fix TTL clock starting at `memoize` definition time instead of first method call
-- Fix metrics key silently dropping kwargs, causing methods that differ only in kwargs to share a metrics bucket
-- Fix stale LRU references remaining after expired entries are pruned
-- Add `ttl:` option to `warm_memo` so warmed entries can be given an expiry
-- Add `max_size:` support for `shared: true` memoization (class-level LRU eviction)
-- Add `ttl_refresh: true` option on `memoize` for sliding window TTL — resets expiry on every cache hit
-- Add `include_protected:` and `include_private:` options to `memoize_all`
-- Add `memo_ttl_remaining` for TTL introspection — returns seconds until expiry, `nil` for no TTL, `0` for uncached/expired
+### Added   
+
+- `ttl:` option on `warm_memo` so warmed entries can be given an expiry
+- `max_size:` support for `shared: true` memoization (class-level LRU eviction)
+- `ttl_refresh: true` option on `memoize` for sliding window TTL — resets the expiry clock on every cache hit so the entry only expires after a full TTL of inactivity
+- `include_protected:` and `include_private:` options on `memoize_all`
+- `memo_ttl_remaining` for TTL introspection — returns seconds until expiry, `nil` for no TTL, `0` for uncached or expired
+
+### Fixed
+
+- TTL clock started at `memoize` definition time instead of at first method call
+- Metrics key silently dropped kwargs, causing methods that differ only in kwargs to share a metrics bucket
+- Stale LRU references remained in the order list after expired entries were pruned
 
 ## [0.5.0] - 2026-05-17
 
-- Drop support for Ruby 3.2 (EOL); minimum required version is now Ruby 3.3 
+### Removed
+
+- Support for Ruby 3.2 (EOL); minimum required version is now Ruby 3.3
 
 ## [0.4.0] - 2026-05-17
 
-- Add `warm_memo`, `dump_memo`, and `load_memo` for cache warm-up and persistence
-  - `warm_memo(:method, *args, **kwargs) { value }` — pre-populates a cache entry via block without calling the method
-  - `dump_memo` / `dump_memo(:method)` — exports live cached entries as a plain `{[method, args, kwargs] => value}` hash
-  - `load_memo(snapshot)` — merges a snapshot into the cache; loaded entries have no TTL
-  - Expired entries are excluded from `dump_memo` output
-- Add `shared: true` option on `memoize` to store results on the class instead of per-instance
-  - All instances share one cache; the method is computed only once regardless of how many objects exist
-  - Class-level invalidation: `reset_shared_memo`, `reset_all_shared_memos`
-  - Class-level inspection: `shared_memoized?`, `shared_memo_count`
-    - Supports `ttl:`, `if:`, and `unless:` options
-  - Instance hooks (`on_memo_hit`, `on_memo_miss`, `on_memo_expire`) fire on the calling instance
-- Add `memoize_all` to memoize every public method defined on the class in one call
-  - Accepts all options supported by `memoize` (`ttl:`, `max_size:`, `if:`, `unless:`)
-  - `except:` option to skip specific methods by name
-  - Only affects public methods defined directly on the class
-- Add `on_memo_miss` hook that fires on every cache miss, completing the full lifecycle hook set alongside `on_memo_hit`, `on_memo_evict`, and `on_memo_expire`
+### Added
+
+- `warm_memo`, `dump_memo`, and `load_memo` for cache warm-up and persistence — pre-populate entries without calling the method, export live entries as a plain hash, and restore from a snapshot
+- `shared: true` option on `memoize` to store results on the class instead of per-instance — includes `reset_shared_memo`, `reset_all_shared_memos`, `shared_memoized?`, and `shared_memo_count`; supports `ttl:`, `if:`, and `unless:`
+- `memoize_all` to memoize every public method defined on the class in one call — accepts all `memoize` options plus `except:` to skip specific methods
+- `on_memo_miss` hook that fires on every cache miss, completing the full lifecycle hook set
 
 ## [0.3.0] - 2026-05-15
 
-- Add `on_memo_hit` hook that fires on every cache hit, completing the lifecycle API alongside `on_memo_expire` and `on_memo_evict`
-- Add conditional memoization via `if:` and `unless:` options on `memoize`
-  - `if: ->(result) { ... }` — only caches when the lambda returns truthy
-  - `unless: ->(result) { ... }` — skips caching when the lambda returns truthy
-  - Uncached calls recompute on every invocation until the condition is met
-    - Compatible with `ttl:`, `max_size:`, hooks, and all inspection APIs 
-- Add LRU cache size limit via `max_size:` option on `memoize`
-  - Evicts the least-recently-used entry per method when the limit is reached
-  - Cache hits promote entries to most-recently-used, preventing premature eviction
-  - Fires the existing `on_evict` hook for LRU-evicted entries
-  - Self-healing: stale LRU references left by `reset_memo` are pruned automatically
-  - Compatible with `ttl:` option and all existing inspection/reset APIs
-  - Thread-safe under concurrent access
+### Added
+
+- `on_memo_hit` hook that fires on every cache hit
+- Conditional memoization via `if:` and `unless:` predicates on `memoize` — uncached calls recompute on every invocation until the condition is satisfied; composes with `ttl:`, `max_size:`, and hooks
+- LRU cache size limit via `max_size:` on `memoize` — evicts the least-recently-used entry when the limit is reached; cache hits promote entries; fires `on_evict`; thread-safe
 
 ## [0.2.0] - 2026-05-14
 
-- Add optional TTL expiration support for memoized entries
-- Add cache invalidation/expiration hooks for custom handlers
-  - `on_memo_expire` hook fires when TTL entries expire
-  - `on_memo_evict` hook fires when manually resetting cache entries
-  - `clear_memo_hooks` to remove registered hooks
-- Add cache statistics and monitoring capabilities
-  - `cache_stats` for comprehensive cache metrics
-  - `cache_stats_for(method_name)` for per-method statistics
-  - `cache_hit_rate` and `cache_miss_rate` for performance analysis
-  - `cache_metrics_reset` to clear collected metrics
-- Add manual cache key generation support
-  - `memoize_with_custom_key` to define custom cache key logic
-  - `clear_custom_keys` to remove custom key generators
-  - Support for complex and computed keys based on arguments
+### Added
+
+- Optional TTL expiration for memoized entries
+- `on_memo_expire` and `on_memo_evict` lifecycle hooks; `clear_memo_hooks` to remove registered hooks
+- Cache metrics: `cache_stats`, `cache_stats_for`, `cache_hit_rate`, `cache_miss_rate`, and `cache_metrics_reset`
+- Custom cache key generation via `memoize_with_custom_key` and `clear_custom_keys`
 
 ## [0.1.2] - 2026-05-13
 
-- Preserve public, protected, and private visibility for memoized methods
-- Allow reset_memo to clear one cached argument combination or all entries for a method
-- Add a memoized? helper for checking whether a method call is already cached
-- Add a memo_count helper for inspecting cache size per instance or method
-- Add a memo_keys helper for inspecting cached argument signatures
-- Add a memo_values helper for inspecting cached signatures and their values
+### Added
+
+- Method visibility preservation (public, protected, private) for memoized methods
+- Targeted `reset_memo` — clear one cached argument combination or all entries for a method
+- `memoized?` helper to check whether a specific call is cached
+- `memo_count`, `memo_keys`, and `memo_values` helpers for cache introspection
 
 ## [0.1.1] - 2026-05-13
 
-- Add automated release tooling plus a GitHub Actions workflow for RubyGems publishing and GitHub releases
+### Added
+
+- Automated release tooling (`bin/release`) and GitHub Actions workflow for RubyGems publishing and GitHub releases
 
 ## [0.1.0] - 2026-02-26
 
+### Added
+
 - Initial release
+
+[Unreleased]: https://github.com/eclectic-coding/safe_memoize/compare/v0.7.0...HEAD
+[0.7.0]: https://github.com/eclectic-coding/safe_memoize/compare/v0.6.3...v0.7.0
+[0.6.3]: https://github.com/eclectic-coding/safe_memoize/compare/v0.6.2...v0.6.3
+[0.6.2]: https://github.com/eclectic-coding/safe_memoize/compare/v0.6.1...v0.6.2
+[0.6.1]: https://github.com/eclectic-coding/safe_memoize/compare/v0.6.0...v0.6.1
+[0.6.0]: https://github.com/eclectic-coding/safe_memoize/compare/v0.5.0...v0.6.0
+[0.5.0]: https://github.com/eclectic-coding/safe_memoize/compare/v0.4.0...v0.5.0
+[0.4.0]: https://github.com/eclectic-coding/safe_memoize/compare/v0.3.0...v0.4.0
+[0.3.0]: https://github.com/eclectic-coding/safe_memoize/compare/v0.2.0...v0.3.0
+[0.2.0]: https://github.com/eclectic-coding/safe_memoize/compare/v0.1.2...v0.2.0
+[0.1.2]: https://github.com/eclectic-coding/safe_memoize/compare/v0.1.1...v0.1.2
+[0.1.1]: https://github.com/eclectic-coding/safe_memoize/compare/v0.1.0...v0.1.1
+[0.1.0]: https://github.com/eclectic-coding/safe_memoize/releases/tag/v0.1.0