safe_memoize 0.7.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 41e3b8e3232ef52d536166c4e701a99a8d7a1e86e2c6d07493d1838d904dbef6
-  data.tar.gz: dac922ad348d3ccf14d8946035b5a0e7709cacc899dcc6e0713da77c980ac6ca
+  metadata.gz: 62f1dae5d57d99d59fe20d981bca17d04bd1ff5b9dd09175770a51bf3d49dd03
+  data.tar.gz: fade31de5124ed4b4f5d88f8bd62aaf750ec03cb22bdf97889fed2283ad3a58d
 SHA512:
-  metadata.gz: a7f263ac2b16ff248ccf6afa158aaaae5a7fd69cadef68ff6926c3d96257378df8d4295f2eac8278a68de12492128282c1ffea42da95c178de7e5619981c8634
-  data.tar.gz: b50610d8ac36d0c7ff4fe9ed174a7f7864654f4178bc5778a9555eda1d934320b7ee0bcf4de53919e9dfacc35d06d8320f0b9dc8e8a25d6fab6808dfb0c0aab4
+  metadata.gz: e742795adaef41bc07e32d1ffb0a1f78335eae46daca57dca3b6b27cf4fc1eb6a58e1636e05d21814336ab3e54468b6ffbe0a4ea52f017c00b0df1a70b98eaeb
+  data.tar.gz: 92b1cb813ed3c54e18408fed0f79f2e9f4983672660f6ee1cf6c0ec9628577fbebf1055797e9d9a4c53ca5b293427c66d9c946a770a443e77b98c77c0937d244

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,147 @@
+# 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.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

data/README.md

@@ -1,5 +1,11 @@
 # SafeMemoize
 
+[![CI](https://github.com/eclectic-coding/safe_memoize/actions/workflows/ci.yml/badge.svg)](https://github.com/eclectic-coding/safe_memoize/actions/workflows/ci.yml)
+[![Gem Version](https://img.shields.io/gem/v/safe_memoize)](https://rubygems.org/gems/safe_memoize)
+[![Total Downloads](https://img.shields.io/gem/dt/safe_memoize)](https://rubygems.org/gems/safe_memoize)
+[![Ruby](https://img.shields.io/badge/ruby-%3E%3D%203.3-CC342D)](https://www.ruby-lang.org)
+[![codecov](https://codecov.io/gh/eclectic-coding/safe_memoize/graph/badge.svg)](https://codecov.io/gh/eclectic-coding/safe_memoize)
+
 Thread-safe memoization for Ruby that correctly handles `nil` and `false` values.
 
 SafeMemoize is a production-ready, zero-dependency memoization library for Ruby. It wraps methods with a `prepend`-based cache that handles everything the standard `||=` idiom gets wrong: `nil` and `false` return values are cached correctly, per-argument result maps eliminate redundant computation for parameterized methods, and a per-instance `Mutex` with double-check locking makes the whole thing safe under concurrent load.
@@ -562,6 +568,10 @@ To preview the changelog/version update without changing anything, use:
 bin/release 0.1.1 --dry-run
 ```
 
+## Roadmap
+
+See [ROADMAP.md](ROADMAP.md) for the planned path from v0.7.0 to v1.0.0 and beyond, including upcoming features, API stability goals, and the versioning policy.
+
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/eclectic-coding/safe_memoize.

data/ROADMAP.md

@@ -0,0 +1,92 @@
+# SafeMemoize Roadmap
+
+This document tracks the planned evolution of SafeMemoize through v1.0.0 and beyond. Items are grouped by release milestone; ordering within a milestone reflects priority, not a strict implementation sequence.
+
+---
+
+## v0.9.0 — Observability & Ecosystem Integration
+
+*Goal: make SafeMemoize a first-class citizen in Rails/ActiveSupport stacks and in observability pipelines.*
+
+| Feature | Description | Status |
+|---|---|---|
+| ActiveSupport::Notifications integration | Emit `cache.hit`, `cache.miss`, `cache.evict`, and `cache.expire` events when ActiveSupport is available (opt-in via configuration) | Planned |
+| StatsD adapter | Thin optional module (`SafeMemoize::Adapters::StatsD`) that routes lifecycle hooks to a StatsD client with sensible metric names and tags | Planned |
+| OpenTelemetry spans | Optional adapter (`SafeMemoize::Adapters::OpenTelemetry`) wrapping computation time in a trace span for distributed tracing pipelines | Planned |
+| Rails request-scope helper | Guide + optional mixin for resetting instance memos at the end of each request (controller concern, middleware, or Active Model pattern) | Planned |
+| Formal benchmark suite | `benchmarks/` directory with comparisons against `memery`, `memo_wise`, and raw `||=`, covering single-threaded throughput and contention under concurrent load | Planned |
+| Concurrency stress tests | Dedicated spec suite hammering shared-cache paths and LRU eviction under high thread counts to surface race conditions | Planned |
+
+---
+
+## v1.0.0 — Stable API
+
+*Goal: declare a stable, semver-governed public API that downstream code can depend on with confidence.*
+
+| Feature | Description | Status |
+|---|---|---|
+| Semantic versioning guarantee | Document which constants, methods, and option keys are public API; breaking changes require a major bump henceforth | Planned |
+| Complete RBS + Sorbet signatures | Cover all public methods including overloads for optional keyword arguments; publish `.rbi` stubs as a companion package if demand warrants | Planned |
+| Full API reference | Generated documentation hosted on RubyDoc or a dedicated docs site; all public methods documented with parameter types, return values, and usage examples | Planned |
+| Ractor compatibility audit | Investigate and either support Ractor-compatible operation (Mutex replacement, shared-cache storage) or document the limitation clearly | Planned |
+| Ruby version policy | Formalise the supported Ruby version window and cadence for dropping EOL versions | Planned |
+| Deprecation sweep | Resolve or formally deprecate any unstable internal APIs before the stable release | Planned |
+| Upgrade guide | Document all breaking changes from 0.x and provide a migration path for users of deprecated behaviour | Planned |
+
+---
+
+## v1.1.0 — Pluggable Cache Stores
+
+*Goal: allow the in-process hash cache to be swapped for an external store, enabling cross-process and distributed memoization.*
+
+| Feature | Description | Status |
+|---|---|---|
+| Cache store adapter interface | Define a minimal read/write/delete/clear/keys contract that external backends must implement | Planned |
+| `store:` option on `memoize` | Accept any store adapter object; defaults to the existing in-process hash store | Planned |
+| Redis adapter | Reference implementation (`SafeMemoize::Stores::Redis`) with TTL, LRU-like expiry, and serialization handled transparently | Planned |
+| Rails.cache adapter | Thin wrapper around `ActiveSupport::Cache::Store` for projects already using a configured Rails cache | Planned |
+| Global default store | Set via `SafeMemoize.configure` — applies a default store to every memoized method without per-call configuration | Planned |
+
+---
+
+## v1.2.0 — Async & Fiber-Safe Memoization
+
+*Goal: first-class support for Fiber-based concurrency frameworks (Async, Falcon, Rails async controllers).*
+
+| Feature | Description | Status |
+|---|---|---|
+| Fiber-local memoization mode | `memoize :method, fiber_local: true` stores results in `Fiber[:safe_memoize_cache]` rather than instance variables, giving each fiber its own isolated cache automatically reset when the fiber terminates | Planned |
+| Ractor-compatible shared cache | Revisit `shared: true` using `Ractor::TVar` or shareable frozen objects so class-level caches work across Ractors | Planned |
+| concurrent-ruby integration | Optional adapter using `Concurrent::Map` and `Concurrent::ReentrantReadWriteLock` as a drop-in replacement for `Mutex` where higher read-concurrency is desirable | Planned |
+
+---
+
+## v2.0.0 — Next Generation (Long Horizon)
+
+*Goal: incorporate real-world usage feedback, clean up accumulated API surface, and open a path for advanced extension.*
+
+| Feature | Description | Status |
+|---|---|---|
+| Plugin / extension architecture | A formal `SafeMemoize::Extension` API so third-party gems can add new options, hooks, or store adapters without monkey-patching | Planned |
+| DSL refinements | Evaluate alternative syntax proposals (`memoize_method`, block form, annotation approach) based on community feedback; introduce the preferred form with a migration path from the current API | Planned |
+| Cross-instance cache sharing | Beyond the class-level `shared: true`, support explicitly named shared caches that span unrelated classes | Planned |
+| Cache namespacing | Allow a namespace prefix on all keys for multi-tenant or versioned deployments (especially useful with external stores) | Planned |
+| Automatic cache busting | Optional integration with ActiveRecord's `updated_at` timestamp so object mutations automatically invalidate their own cached entries | Planned |
+
+---
+
+## Versioning policy
+
+SafeMemoize follows [Semantic Versioning](https://semver.org/) from v1.0.0 onwards:
+
+- **Patch** (1.x.**y**) — bug fixes; no API changes
+- **Minor** (1.**x**.0) — additive features; backward-compatible
+- **Major** (**x**.0.0) — breaking changes; migration guide published
+
+0.x releases may include breaking changes between minor versions.
+
+---
+
+## Contributing
+
+Ideas, bug reports, and pull requests are welcome. Open an issue at <https://github.com/eclectic-coding/safe_memoize/issues> to discuss a feature before building it. If you are picking up a roadmap item, mention the milestone in your PR so it can be tracked against this document.

data/lib/safe_memoize/class_methods.rb

@@ -4,6 +4,11 @@ module SafeMemoize
   module ClassMethods
     def memoize(method_name, ttl: nil, max_size: nil, ttl_refresh: false, if: nil, unless: nil, shared: false, key: nil)
       method_name = method_name.to_sym
+
+      unless method_defined?(method_name) || private_method_defined?(method_name) || protected_method_defined?(method_name)
+        raise ArgumentError, "cannot memoize :#{method_name} — no instance method with that name is defined on #{self}"
+      end
+
       visibility = memoized_method_visibility(method_name)
 
       config = SafeMemoize.configuration
@@ -274,8 +279,11 @@ module SafeMemoize
       end
     end
 
-    def memoize_all(except: [], include_protected: false, include_private: false, **options)
+    def memoize_all(except: [], only: [], include_protected: false, include_private: false, **options)
+      raise ArgumentError, "cannot specify both :only and :except" if only.any? && except.any?
+
       excluded = Array(except).map(&:to_sym)
+      included = Array(only).map(&:to_sym)
 
       methods = public_instance_methods(false)
       methods |= protected_instance_methods(false) if include_protected
@@ -283,6 +291,7 @@ module SafeMemoize
 
       methods.each do |method_name|
         next if excluded.include?(method_name)
+        next if included.any? && !included.include?(method_name)
 
         memoize(method_name, **options)
       end

data/lib/safe_memoize/configuration.rb

@@ -2,11 +2,13 @@
 
 module SafeMemoize
   class Configuration
-    attr_accessor :default_ttl, :default_max_size
+    attr_accessor :default_ttl, :default_max_size, :on_deprecation, :on_hook_error
 
     def initialize
       @default_ttl = nil
       @default_max_size = nil
+      @on_deprecation = nil
+      @on_hook_error = nil
     end
   end
 end

data/lib/safe_memoize/hooks_methods.rb

@@ -19,7 +19,16 @@ module SafeMemoize
 
     def call_memo_hooks(hook_type, cache_key, record)
       hooks = memo_hook_store[hook_type] || []
-      hooks.each { |hook| hook.call(cache_key, record) }
+      hooks.each do |hook|
+        hook.call(cache_key, record)
+      rescue => error
+        handler = SafeMemoize.configuration.on_hook_error
+        if handler
+          handler.call(error, hook_type, cache_key)
+        else
+          warn "[SafeMemoize] Hook error in #{hook_type}: #{error.message}"
+        end
+      end
     end
 
     def _clear_memo_hooks(hook_type = nil)

data/lib/safe_memoize/inspection_methods.rb

@@ -69,7 +69,20 @@ module SafeMemoize
     end
 
     def safe_memo_cache_key(method_name, args, kwargs)
-      [method_name.to_sym, args, kwargs]
+      [method_name.to_sym, deep_freeze_copy(args), deep_freeze_copy(kwargs)]
+    end
+
+    def deep_freeze_copy(obj)
+      case obj
+      when Array
+        obj.map { |e| deep_freeze_copy(e) }.freeze
+      when Hash
+        obj.each_with_object({}) { |(k, v), h| h[deep_freeze_copy(k)] = deep_freeze_copy(v) }.freeze
+      when String
+        -obj
+      else
+        obj
+      end
     end
   end
 end

data/lib/safe_memoize/public_methods.rb

@@ -226,5 +226,48 @@ module SafeMemoize
         lru_clear_all
       end
     end
+
+    def memo_inspect(method_name, *args, **kwargs)
+      method_name = method_name.to_sym
+      cache_key = compute_cache_key(method_name, args, kwargs)
+
+      with_memo_lock do
+        record = memo_cache_record(cache_key)
+        return nil unless record
+
+        now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+        ttl_remaining = if record[:expires_at]
+          remaining = record[:expires_at] - now
+          (remaining > 0) ? remaining.round(6) : 0
+        end
+
+        age = (now - record[:cached_at]).round(6) if record[:cached_at]
+
+        metrics_key = safe_memo_cache_key(method_name, args, kwargs)
+        entry_metrics = memo_metrics_store[metrics_key] || {hits: 0, misses: 0}
+
+        custom_key = (cache_key.length == 2) ? cache_key[1] : nil
+
+        lru_position = begin
+          method_lru = lru_order_store[method_name]
+          if method_lru&.key?(cache_key)
+            keys = method_lru.keys
+            keys.length - keys.index(cache_key)
+          end
+        end
+
+        {
+          cached: true,
+          value: memo_record_value(record),
+          hits: entry_metrics[:hits],
+          misses: entry_metrics[:misses],
+          ttl_remaining: ttl_remaining,
+          age: age,
+          custom_key: custom_key,
+          lru_position: lru_position
+        }
+      end
+    end
   end
 end

data/lib/safe_memoize/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module SafeMemoize
-  VERSION = "0.7.0"
+  VERSION = "0.8.0"
 end

data/lib/safe_memoize.rb

@@ -35,4 +35,10 @@ module SafeMemoize
   def self.reset_configuration!
     @configuration = Configuration.new
   end
+
+  def self.deprecate(subject, message:, horizon:)
+    text = "[SafeMemoize] #{subject} is deprecated and will be removed in #{horizon}. #{message}"
+    handler = configuration.on_deprecation
+    handler ? handler.call(text) : warn(text)
+  end
 end

data/sig/safe_memoize.rbs

@@ -17,17 +17,20 @@ module SafeMemoize
   def self.configure: () { (Configuration) -> void } -> void
   def self.configuration: () -> Configuration
   def self.reset_configuration!: () -> Configuration
+  def self.deprecate: (String subject, message: String, horizon: String) -> void
 
   class Configuration
     attr_accessor default_ttl: Numeric?
     attr_accessor default_max_size: Integer?
+    attr_accessor on_deprecation: (^(String message) -> void)?
+    attr_accessor on_hook_error: (^(Exception error, Symbol hook_type, untyped cache_key) -> void)?
 
     def initialize: () -> void
   end
 
   module ClassMethods
     def memoize: (Symbol | String method_name, ?ttl: Numeric?, ?max_size: Integer?, ?ttl_refresh: bool, ?if: (^(untyped result) -> boolish)?, ?unless: (^(untyped result) -> boolish)?, ?shared: bool, ?key: (^(*untyped args, **untyped kwargs) -> untyped)?) -> void
-    def memoize_all: (?except: Array[Symbol | String], ?include_protected: bool, ?include_private: bool, ?ttl: Numeric?, ?max_size: Integer?, ?if: (^(untyped result) -> boolish)?, ?unless: (^(untyped result) -> boolish)?, ?shared: bool, ?key: (^(*untyped args, **untyped kwargs) -> untyped)?) -> void
+    def memoize_all: (?except: Array[Symbol | String], ?only: Array[Symbol | String], ?include_protected: bool, ?include_private: bool, ?ttl: Numeric?, ?max_size: Integer?, ?if: (^(untyped result) -> boolish)?, ?unless: (^(untyped result) -> boolish)?, ?shared: bool, ?key: (^(*untyped args, **untyped kwargs) -> untyped)?) -> void
     def reset_shared_memo: (Symbol | String method_name, *untyped args, **untyped kwargs) -> void
     def reset_all_shared_memos: () -> void
     def shared_memoized?: (Symbol | String method_name, *untyped args, **untyped kwargs) -> bool
@@ -68,6 +71,7 @@ module SafeMemoize
     def memo_stale?: (Symbol | String method_name, *untyped args, **untyped kwargs) -> bool
     def reset_memo: (Symbol | String method_name, *untyped args, **untyped kwargs) -> void
     def reset_all_memos: () -> void
+    def memo_inspect: (Symbol | String method_name, *untyped args, **untyped kwargs) -> { cached: bool, value: untyped, hits: Integer, misses: Integer, ttl_remaining: Float?, age: Float?, custom_key: untyped, lru_position: Integer? }?
   end
 
   module CacheStoreMethods
@@ -108,6 +112,7 @@ module SafeMemoize
     def safe_memo_values_for: (Symbol? method_name) -> Array[untyped]
     def memo_projection: (memo_key cache_key, memo_record value, include_method: bool, include_value: bool) -> Hash[Symbol, untyped]
     def safe_memo_cache_key: (Symbol | String method_name, Array[untyped] args, Hash[Symbol, untyped] kwargs) -> default_memo_key
+    def deep_freeze_copy: (untyped obj) -> untyped
   end
 
   module HooksMethods

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: safe_memoize
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.8.0
 platform: ruby
 authors:
 - Chuck Smith
@@ -34,7 +34,7 @@ description: 'SafeMemoize is a production-ready, zero-dependency memoization lib
   cache key generators, and introspection helpers. Method visibility (public, protected,
   private) is fully preserved.'
 email:
-- eclectic-coding@users.noreply.github.com
+- chuck@eclecticcoding.com
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -44,6 +44,7 @@ files:
 - CHANGELOG.md
 - LICENSE.txt
 - README.md
+- ROADMAP.md
 - Rakefile
 - lib/safe_memoize.rb
 - lib/safe_memoize/cache_metrics_methods.rb