safe_memoize 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4806562a18a6f5143379d638d270ea3552280637dd33ed322c0f667f1257d836
-  data.tar.gz: bdb12e7ae3a41d230c85fd24750edcc5eeba4d90cf2ac93b59cd0bccc8ba0325
+  metadata.gz: 945c98062bb51a6f19e3f229da2f8315680f1aea9ac290d1e9d60924ff6a6b6d
+  data.tar.gz: aa74ec52245abaf6fb6835446546cb269b919e07d98088b5f15f589543c1c2f7
 SHA512:
-  metadata.gz: 4799eb0209980d5fee072ae05ff1661d70b8db5869e8701cac3fcd9241c1106f17fa84a798f85bcb084c197c24c646e2996fe60fa7375d4db8d780ad3bc4b71a
-  data.tar.gz: 6d64a7e4bef4d5b3825d903294bc955c1ec483157aee479496e001cb500e6128804e148791793d862938543bf5e9e7ee05cca128adb4bb37e68a9d4858bcb517
+  metadata.gz: a2fd80a5146bf93a91a36e4449abc4e83d3687d6dbbf91b6323150847b5909b6f69ff25ef75e1804c2217a2652ca148357eaf19dccd7cdc3c2cf60ef255a5121
+  data.tar.gz: d415cc760c97f1e8d3e50f33802279c065c6c56e7f89cc553717538824663b47ff974a9cbe57ccb064638d630892a837eb10cd7602db1a8c50618a52e040fe05

data/.github/workflows/ci.yml

@@ -0,0 +1,38 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: Ruby ${{ matrix.ruby }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby:
+          - "3.2"
+          - "3.3"
+          - "3.4"
+          - "4.0"
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v5
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+          bundler-cache: true
+
+      - name: Run test and lint suite
+        run: bundle exec rake
+

data/.github/workflows/release.yml

@@ -0,0 +1,91 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: write
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "3.4"
+          bundler-cache: true
+
+      - name: Verify tag matches gem version
+        env:
+          RELEASE_TAG: ${{ github.ref_name }}
+        run: |
+          expected_version="${RELEASE_TAG#v}"
+          actual_version="$(bundle exec ruby -e 'require_relative "lib/safe_memoize/version"; print SafeMemoize::VERSION')"
+
+          if [ "$actual_version" != "$expected_version" ]; then
+            echo "Tag $expected_version does not match gem version $actual_version"
+            exit 1
+          fi
+
+      - name: Run test suite
+        run: bundle exec rake
+
+      - name: Build gem artifact
+        env:
+          RELEASE_TAG: ${{ github.ref_name }}
+        run: |
+          version="${RELEASE_TAG#v}"
+          mkdir -p pkg
+          gem build safe_memoize.gemspec --output "pkg/safe_memoize-${version}.gem"
+
+      - name: Check whether the gem version is already on RubyGems
+        id: rubygems
+        env:
+          RELEASE_TAG: ${{ github.ref_name }}
+        run: |
+          version="${RELEASE_TAG#v}"
+
+          if ruby -rjson -ropen-uri -e 'version = ARGV.fetch(0); versions = JSON.parse(URI.open("https://rubygems.org/api/v1/versions/safe_memoize.json", &:read)); exit(versions.any? { |item| item["number"] == version } ? 0 : 1)' "$version"; then
+            echo "already_published=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "already_published=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Skip RubyGems publish for existing versions
+        if: steps.rubygems.outputs.already_published == 'true'
+        env:
+          RELEASE_TAG: ${{ github.ref_name }}
+        run: echo "RubyGems already has version ${RELEASE_TAG#v}; skipping gem push."
+
+      - 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}"
+          gem push "pkg/safe_memoize-${version}.gem"
+
+      - name: Generate GitHub release notes from CHANGELOG
+        env:
+          RELEASE_TAG: ${{ github.ref_name }}
+        run: |
+          version="${RELEASE_TAG#v}"
+          bundle exec ruby bin/release_notes "$version" "${RUNNER_TEMP}/release_notes.md"
+
+      - name: Create GitHub release
+        uses: softprops/action-gh-release@v2
+        with:
+          body_path: ${{ runner.temp }}/release_notes.md
+          files: pkg/*.gem
+          tag_name: ${{ github.ref_name }}
+

data/CHANGELOG.md

@@ -1,5 +1,35 @@
 ## [Unreleased]
 
+## [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
+
+## [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
+
+## [0.1.1] - 2026-05-13
+
+- Add automated release tooling plus a GitHub Actions workflow for RubyGems publishing and GitHub releases
+
 ## [0.1.0] - 2026-02-26
 
 - Initial release

data/README.md

@@ -21,6 +21,13 @@ SafeMemoize uses `Hash#key?` to distinguish "not yet cached" from "cached nil/fa
 - Thread-safe via double-check locking
 - Zero runtime dependencies
 - Simple `prepend` + `memoize` API
+- Preserves public, protected, and private method visibility
+- Supports targeted cache invalidation by argument combination
+- Includes a `memoized?` helper for cache inspection
+- Includes a `memo_count` helper for cache size stats
+- Includes a `memo_keys` helper for inspecting cached signatures
+- Includes a `memo_values` helper for inspecting cached signatures and values
+- Optional TTL expiration support for cached entries
 - Block arguments bypass cache (blocks aren't comparable)
 
 ## Installation
@@ -94,12 +101,66 @@ class Config
 end
 ```
 
+### Works with private methods
+
+```ruby
+class TokenProvider
+  prepend SafeMemoize
+
+  def bearer_token
+    token
+  end
+
+  private
+
+  def token
+    fetch_token_from_service
+  end
+  memoize :token
+end
+```
+
 ### Cache reset
 
 ```ruby
 obj = MyService.new
-obj.reset_memo(:current_user)  # Clears cache for one method
-obj.reset_all_memos            # Clears all memoized values
+obj.reset_memo(:current_user)                    # Clears all cached entries for one method
+obj.reset_memo(:find_user, 42)                  # Clears only the cached call for find_user(42)
+obj.reset_memo(:search, "ruby", page: 2)       # Clears one positional/keyword combination
+obj.reset_all_memos                             # Clears all memoized values
+```
+
+### TTL expiration
+
+```ruby
+class QuoteService
+  prepend SafeMemoize
+
+  def current_quote
+    fetch_quote_from_api
+  end
+  memoize :current_quote, ttl: 60
+end
+```
+
+With a TTL, cached values expire automatically after the given number of seconds. The next call recomputes and refreshes the cache.
+
+### Cache inspection
+
+```ruby
+obj = MyService.new
+
+obj.memoized?(:current_user)              # => false
+obj.current_user
+obj.memoized?(:current_user)              # => true
+
+obj.memoized?(:search, "ruby", page: 2)  # Checks one cached argument combination
+obj.memo_count                            # Total cached entries for this instance
+obj.memo_count(:search)                   # Cached entries for one method
+obj.memo_keys                             # All cached signatures with method, args, kwargs
+obj.memo_keys(:search)                    # Cached signatures for one method
+obj.memo_values                           # Cached signatures and values for all methods
+obj.memo_values(:search)                  # Cached signatures and values for one method
 ```
 
 ## How It Works
@@ -110,6 +171,41 @@ SafeMemoize uses Ruby's `prepend` mechanism. When you call `memoize :method_name
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `bundle exec rspec` to run the tests. You can also run `bin/console` for an interactive prompt.
 
+GitHub Actions also runs the full `bundle exec rake` suite automatically for pull requests, manual workflow runs, and pushes to `main` via `.github/workflows/ci.yml`.
+
+## Releasing
+
+Releases are automated in two parts:
+
+1. Run `bin/release VERSION` locally to:
+   - update `lib/safe_memoize/version.rb`
+   - convert the current `## [Unreleased]` section in `CHANGELOG.md` into a dated release entry
+   - create the release commit and annotated tag
+2. Push the branch and tag to GitHub. The workflow in `.github/workflows/release.yml` will:
+   - run the test and lint suite
+   - build the gem
+   - push it to RubyGems when that version is not already published
+   - create a GitHub release using the matching section from `CHANGELOG.md`
+
+One-time setup:
+
+- add a `RUBYGEMS_API_KEY` repository secret in GitHub
+
+Typical release flow:
+
+```bash
+bundle exec rake
+bin/release 0.1.1
+git push origin HEAD
+git push origin v0.1.1
+```
+
+To preview the changelog/version update without changing anything, use:
+
+```bash
+bin/release 0.1.1 --dry-run
+```
+
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/eclectic-coding/safe_memoize.

data/lib/safe_memoize/cache_metrics_methods.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module SafeMemoize
+  module CacheMetricsMethods
+    private
+
+    def memo_metrics_store
+      @__safe_memo_metrics__ ||= {}
+    end
+
+    def record_cache_hit(method_name, args)
+      cache_key = safe_memo_cache_key(method_name, args, {})
+      metrics = memo_metrics_store
+      metrics[cache_key] ||= {hits: 0, misses: 0, total_time: 0.0}
+      metrics[cache_key][:hits] += 1
+    end
+
+    def record_cache_miss(method_name, args, computation_time)
+      cache_key = safe_memo_cache_key(method_name, args, {})
+      metrics = memo_metrics_store
+      metrics[cache_key] ||= {hits: 0, misses: 0, total_time: 0.0}
+      metrics[cache_key][:misses] += 1
+      metrics[cache_key][:total_time] += computation_time
+    end
+
+    def _reset_cache_metrics
+      @__safe_memo_metrics__ = {}
+    end
+  end
+end

data/lib/safe_memoize/cache_record_methods.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module SafeMemoize
+  module CacheRecordMethods
+    private
+
+    def memo_ttl(ttl)
+      return nil if ttl.nil?
+
+      ttl = Float(ttl)
+      raise ArgumentError, "ttl must be non-negative" if ttl < 0
+
+      ttl
+    rescue ArgumentError, TypeError
+      raise ArgumentError, "ttl must be a non-negative number"
+    end
+
+    def memo_expires_at(ttl)
+      return nil unless ttl
+
+      Process.clock_gettime(Process::CLOCK_MONOTONIC) + ttl
+    end
+
+    def memo_record(value, expires_at:)
+      {value: value, expires_at: expires_at}
+    end
+
+    def memo_record_value(record)
+      record[:value]
+    end
+
+    def memo_record_live?(record)
+      return false unless record
+
+      expires_at = record[:expires_at]
+      return true unless expires_at
+
+      expires_at > Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+
+    def memo_prune_expired_entries!(cache)
+      cache.delete_if do |cache_key, record|
+        if !memo_record_live?(record)
+          call_memo_hooks(:on_expire, cache_key, record)
+          true
+        else
+          false
+        end
+      end
+    end
+  end
+end

data/lib/safe_memoize/cache_store_methods.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module SafeMemoize
+  module CacheStoreMethods
+    private
+
+    def with_memo_lock
+      if defined?(@__safe_memo_mutex__) && @__safe_memo_mutex__
+        @__safe_memo_mutex__.synchronize { yield }
+      else
+        yield
+      end
+    end
+
+    def memo_cache_or_nil
+      return nil unless defined?(@__safe_memo_cache__)
+
+      @__safe_memo_cache__
+    end
+
+    def memo_cache_hit?(cache_key)
+      !!memo_cache_record(cache_key)
+    end
+
+    def memo_cache_record(cache_key)
+      cache = memo_cache_or_nil
+      return nil unless cache
+
+      record = cache[cache_key]
+      return nil unless memo_record_live?(record)
+
+      record
+    end
+
+    def memo_cache_read(cache_key)
+      record = memo_cache_record(cache_key)
+      return nil unless record
+
+      memo_record_value(record)
+    end
+
+    def memo_fetch_or_store(cache_key, expires_at: nil)
+      memo_mutex!.synchronize do
+        @__safe_memo_cache__ ||= {}
+
+        record = @__safe_memo_cache__[cache_key]
+
+        if memo_record_live?(record)
+          memo_record_value(record)
+        else
+          value = yield
+          @__safe_memo_cache__[cache_key] = memo_record(value, expires_at: expires_at)
+
+          value
+        end
+      end
+    end
+
+    def memo_mutex!
+      @__safe_memo_mutex__ ||= Mutex.new
+    end
+
+    def with_memo_cache
+      cache = memo_cache_or_nil
+      return nil unless cache
+
+      yield cache
+    end
+  end
+end

data/lib/safe_memoize/class_methods.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module SafeMemoize
+  module ClassMethods
+    def memoize(method_name, ttl: nil)
+      method_name = method_name.to_sym
+      visibility = memoized_method_visibility(method_name)
+
+      ttl = if ttl.nil?
+        nil
+      else
+        ttl = Float(ttl)
+        raise ArgumentError, "ttl must be non-negative" if ttl < 0
+
+        ttl
+      end
+
+      expires_at = ttl && Process.clock_gettime(Process::CLOCK_MONOTONIC) + ttl
+
+      mod = Module.new do
+        define_method(method_name) do |*args, **kwargs, &block|
+          # Blocks bypass cache entirely — they aren't comparable
+          return super(*args, **kwargs, &block) if block
+
+          cache_key = compute_cache_key(method_name, args, kwargs)
+
+          # Fast path: check without lock
+          if (record = memo_cache_record(cache_key))
+            record_cache_hit(method_name, args)
+            return memo_record_value(record)
+          end
+
+          # Cache miss - compute and store
+          start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          result = memo_fetch_or_store(cache_key, expires_at: expires_at) { super(*args, **kwargs) }
+          elapsed_time = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time
+
+          with_memo_lock do
+            record_cache_miss(method_name, args, elapsed_time)
+          end
+
+          result
+        end
+
+        send(visibility, method_name)
+      end
+
+      prepend mod
+    end
+
+    private
+
+    def memoized_method_visibility(method_name)
+      return :private if private_method_defined?(method_name)
+      return :protected if protected_method_defined?(method_name)
+
+      :public
+    end
+  end
+end

data/lib/safe_memoize/custom_key_methods.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module SafeMemoize
+  module CustomKeyMethods
+    private
+
+    def custom_key_store
+      @__safe_memo_custom_keys__ ||= {}
+    end
+
+    def register_custom_key(method_name, &block)
+      raise ArgumentError, "block required" unless block
+
+      method_name = method_name.to_sym
+      custom_key_store[method_name] = block
+    end
+
+    def compute_cache_key(method_name, args, kwargs)
+      method_name = method_name.to_sym
+
+      # Check if a custom key generator is registered
+      custom_key_block = custom_key_store[method_name]
+
+      if custom_key_block
+        # Call the custom key generator with args and kwargs
+        custom_key = custom_key_block.call(*args, **kwargs)
+        # Wrap in a standard format: [method, custom_key]
+        [method_name, custom_key]
+      else
+        # Use default key generation
+        safe_memo_cache_key(method_name, args, kwargs)
+      end
+    end
+
+    def _clear_custom_keys
+      @__safe_memo_custom_keys__ = {}
+    end
+  end
+end

data/lib/safe_memoize/hooks_methods.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module SafeMemoize
+  module HooksMethods
+    private
+
+    def memo_hook_store
+      @__safe_memo_hooks__ ||= {on_expire: [], on_evict: []}
+    end
+
+    def register_memo_hook(hook_type, &block)
+      raise ArgumentError, "block required" unless block
+
+      valid_hooks = [:on_expire, :on_evict]
+      raise ArgumentError, "invalid hook type: #{hook_type}" unless valid_hooks.include?(hook_type)
+
+      memo_hook_store[hook_type] << block
+    end
+
+    def call_memo_hooks(hook_type, cache_key, record)
+      hooks = memo_hook_store[hook_type] || []
+      hooks.each { |hook| hook.call(cache_key, record) }
+    end
+
+    def _clear_memo_hooks(hook_type = nil)
+      if hook_type
+        memo_hook_store[hook_type] = []
+      else
+        @__safe_memo_hooks__ = {on_expire: [], on_evict: []}
+      end
+    end
+  end
+end

data/lib/safe_memoize/inspection_methods.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module SafeMemoize
+  module InspectionMethods
+    private
+
+    def safe_memo_scoped_method(method_name)
+      raise ArgumentError, "expected 0 or 1 arguments" if method_name.length > 1
+
+      method_name.first&.to_sym
+    end
+
+    def memo_matcher_for(method_name, args, kwargs)
+      if args.empty? && kwargs.empty?
+        ->(key) { key[0] == method_name }
+      else
+        cache_key = safe_memo_cache_key(method_name, args, kwargs)
+        ->(key) { key == cache_key }
+      end
+    end
+
+    def memo_entries_for(method_name)
+      cache = memo_cache_or_nil
+      return [] unless cache
+
+      memo_prune_expired_entries!(cache)
+      entries = cache.to_a
+      return entries unless method_name
+
+      entries.select { |(cache_key, _)| cache_key[0] == method_name }
+    end
+
+    def safe_memo_count_for(method_name)
+      memo_entries_for(method_name).length
+    end
+
+    def safe_memo_keys_for(method_name)
+      entries = memo_entries_for(method_name)
+      include_method = method_name.nil?
+
+      entries.map do |(cache_key, value)|
+        memo_projection(cache_key, value, include_method: include_method, include_value: false)
+      end
+    end
+
+    def safe_memo_values_for(method_name)
+      entries = memo_entries_for(method_name)
+      include_method = method_name.nil?
+
+      entries.map do |(cache_key, value)|
+        memo_projection(cache_key, value, include_method: include_method, include_value: true)
+      end
+    end
+
+    def memo_projection(cache_key, value, include_method:, include_value:)
+      method_name, args, kwargs = cache_key
+
+      payload = {args: args, kwargs: kwargs}
+      payload[:method] = method_name if include_method
+      payload[:value] = memo_record_value(value) if include_value
+      payload
+    end
+
+    def safe_memo_cache_key(method_name, args, kwargs)
+      [method_name.to_sym, args, kwargs]
+    end
+  end
+end

data/lib/safe_memoize/instance_methods.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module SafeMemoize
+  module InstanceMethods
+    include PublicMethods
+    include CacheStoreMethods
+    include CacheRecordMethods
+    include InspectionMethods
+    include HooksMethods
+    include CacheMetricsMethods
+    include PublicMetricsMethods
+    include CustomKeyMethods
+    include PublicCustomKeyMethods
+  end
+end

data/lib/safe_memoize/public_custom_key_methods.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module SafeMemoize
+  module PublicCustomKeyMethods
+    def memoize_with_custom_key(method_name, &key_generator)
+      raise ArgumentError, "block required for key generation" unless key_generator
+
+      register_custom_key(method_name, &key_generator)
+    end
+
+    def clear_custom_keys(method_name = nil)
+      if method_name
+        with_memo_lock do
+          custom_key_store.delete(method_name.to_sym)
+        end
+      else
+        with_memo_lock do
+          _clear_custom_keys
+        end
+      end
+    end
+  end
+end

data/lib/safe_memoize/public_methods.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module SafeMemoize
+  module PublicMethods
+    def memoized?(method_name, *args, **kwargs, &block)
+      return false if block
+
+      cache_key = safe_memo_cache_key(method_name, args, kwargs)
+
+      with_memo_lock do
+        memo_cache_hit?(cache_key)
+      end
+    end
+
+    def memo_count(*method_name)
+      scoped_method = safe_memo_scoped_method(method_name)
+
+      with_memo_lock do
+        safe_memo_count_for(scoped_method)
+      end
+    end
+
+    def memo_keys(*method_name)
+      scoped_method = safe_memo_scoped_method(method_name)
+
+      with_memo_lock do
+        safe_memo_keys_for(scoped_method)
+      end
+    end
+
+    def memo_values(*method_name)
+      scoped_method = safe_memo_scoped_method(method_name)
+
+      with_memo_lock do
+        safe_memo_values_for(scoped_method)
+      end
+    end
+
+    def on_memo_expire(&block)
+      raise ArgumentError, "block required" unless block
+
+      register_memo_hook(:on_expire, &block)
+    end
+
+    def on_memo_evict(&block)
+      raise ArgumentError, "block required" unless block
+
+      register_memo_hook(:on_evict, &block)
+    end
+
+    def clear_memo_hooks(hook_type = nil)
+      with_memo_lock do
+        _clear_memo_hooks(hook_type)
+      end
+    end
+
+    def reset_memo(method_name, *args, **kwargs)
+      method_name = method_name.to_sym
+
+      matcher = memo_matcher_for(method_name, args, kwargs)
+
+      with_memo_lock do
+        with_memo_cache do |cache|
+          cache.delete_if do |key, record|
+            if matcher.call(key)
+              call_memo_hooks(:on_evict, key, record)
+              true
+            else
+              false
+            end
+          end
+        end
+      end
+    end
+
+    def reset_all_memos
+      with_memo_lock do
+        if defined?(@__safe_memo_cache__) && @__safe_memo_cache__
+          @__safe_memo_cache__.each do |key, record|
+            call_memo_hooks(:on_evict, key, record)
+          end
+        end
+        @__safe_memo_cache__ = {}
+      end
+    end
+  end
+end

data/lib/safe_memoize/public_metrics_methods.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+module SafeMemoize
+  module PublicMetricsMethods
+    def cache_stats
+      with_memo_lock do
+        metrics = memo_metrics_store
+
+        if metrics.empty?
+          return {
+            total_hits: 0,
+            total_misses: 0,
+            hit_rate: 0.0,
+            miss_rate: 0.0,
+            average_computation_time: 0.0,
+            entries: []
+          }
+        end
+
+        total_hits = metrics.values.sum { |m| m[:hits] }
+        total_misses = metrics.values.sum { |m| m[:misses] }
+        total_time = metrics.values.sum { |m| m[:total_time] }
+        total_calls = total_hits + total_misses
+
+        hit_rate = total_calls.zero? ? 0.0 : (total_hits.to_f / total_calls * 100).round(2)
+        miss_rate = total_calls.zero? ? 0.0 : (total_misses.to_f / total_calls * 100).round(2)
+        avg_time = total_misses.zero? ? 0.0 : (total_time / total_misses).round(6)
+
+        entries = metrics.map do |cache_key, stats|
+          method_name, args, _kwargs = cache_key
+          entry_hit_rate = if (stats[:hits] + stats[:misses]).zero?
+            0.0
+          else
+            (stats[:hits].to_f / (stats[:hits] + stats[:misses]) * 100).round(2)
+          end
+
+          {
+            method: method_name,
+            args: args,
+            hits: stats[:hits],
+            misses: stats[:misses],
+            hit_rate: entry_hit_rate,
+            computation_time: stats[:total_time].round(6)
+          }
+        end
+
+        {
+          total_hits: total_hits,
+          total_misses: total_misses,
+          hit_rate: hit_rate,
+          miss_rate: miss_rate,
+          average_computation_time: avg_time,
+          entries: entries
+        }
+      end
+    end
+
+    def cache_stats_for(method_name)
+      method_name = method_name.to_sym
+
+      with_memo_lock do
+        metrics = memo_metrics_store
+        method_metrics = metrics.select { |key, _| key[0] == method_name }
+
+        if method_metrics.empty?
+          return {
+            method: method_name,
+            total_hits: 0,
+            total_misses: 0,
+            hit_rate: 0.0,
+            miss_rate: 0.0,
+            average_computation_time: 0.0,
+            entries: []
+          }
+        end
+
+        total_hits = method_metrics.values.sum { |m| m[:hits] }
+        total_misses = method_metrics.values.sum { |m| m[:misses] }
+        total_time = method_metrics.values.sum { |m| m[:total_time] }
+        total_calls = total_hits + total_misses
+
+        hit_rate = total_calls.zero? ? 0.0 : (total_hits.to_f / total_calls * 100).round(2)
+        miss_rate = total_calls.zero? ? 0.0 : (total_misses.to_f / total_calls * 100).round(2)
+        avg_time = total_misses.zero? ? 0.0 : (total_time / total_misses).round(6)
+
+        entries = method_metrics.map do |cache_key, stats|
+          _method, args, _kwargs = cache_key
+          entry_hit_rate = if (stats[:hits] + stats[:misses]).zero?
+            0.0
+          else
+            (stats[:hits].to_f / (stats[:hits] + stats[:misses]) * 100).round(2)
+          end
+
+          {
+            args: args,
+            hits: stats[:hits],
+            misses: stats[:misses],
+            hit_rate: entry_hit_rate,
+            computation_time: stats[:total_time].round(6)
+          }
+        end
+
+        {
+          method: method_name,
+          total_hits: total_hits,
+          total_misses: total_misses,
+          hit_rate: hit_rate,
+          miss_rate: miss_rate,
+          average_computation_time: avg_time,
+          entries: entries
+        }
+      end
+    end
+
+    def cache_hit_rate
+      stats = cache_stats
+      stats[:hit_rate]
+    end
+
+    def cache_miss_rate
+      stats = cache_stats
+      stats[:miss_rate]
+    end
+
+    def cache_metrics_reset
+      with_memo_lock do
+        _reset_cache_metrics
+      end
+    end
+  end
+end

data/lib/safe_memoize/release_tooling.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require "date"
+
+module SafeMemoize
+  module ReleaseTooling
+    module_function
+
+    VERSION_PATTERN = /VERSION = "[^"]+"/
+    SEMVER_PATTERN = /\A\d+\.\d+\.\d+(?:[-.][0-9A-Za-z]+(?:[.-][0-9A-Za-z]+)*)?\z/
+    UNRELEASED_HEADING = "## [Unreleased]"
+
+    def normalize_version(version)
+      normalized_version = version.to_s.sub(/\Av/, "")
+
+      unless normalized_version.match?(SEMVER_PATTERN)
+        raise ArgumentError, "version must look like x.y.z"
+      end
+
+      normalized_version
+    end
+
+    def update_version_file(contents, version)
+      normalized_version = normalize_version(version)
+
+      unless contents.match?(VERSION_PATTERN)
+        raise ArgumentError, "version file does not define VERSION"
+      end
+
+      contents.sub(VERSION_PATTERN, %(VERSION = "#{normalized_version}"))
+    end
+
+    def finalize_changelog(contents, version, date = Date.today)
+      normalized_version = normalize_version(version)
+      release_heading = "## [#{normalized_version}] - #{date.iso8601}"
+
+      unless contents.include?(UNRELEASED_HEADING)
+        raise ArgumentError, "CHANGELOG.md must contain an Unreleased heading"
+      end
+
+      if contents.match?(/^## \[#{Regexp.escape(normalized_version)}\](?: - .+)?$/)
+        raise ArgumentError, "CHANGELOG.md already contains #{normalized_version}"
+      end
+
+      contents.sub(UNRELEASED_HEADING, "#{UNRELEASED_HEADING}\n\n#{release_heading}")
+    end
+
+    def extract_release_notes(contents, version)
+      normalized_version = normalize_version(version)
+      lines = contents.lines
+      release_heading = /^## \[#{Regexp.escape(normalized_version)}\](?: - .+)?$/
+      start_index = lines.index { |line| line.match?(release_heading) }
+
+      raise ArgumentError, "CHANGELOG.md is missing release notes for #{normalized_version}" unless start_index
+
+      body = lines[(start_index + 1)..].take_while { |line| !line.start_with?("## [") }.join.strip
+      body = "- No changes listed." if body.empty?
+
+      <<~MARKDOWN
+        ## SafeMemoize #{normalized_version}
+
+        #{body}
+      MARKDOWN
+    end
+  end
+end

data/lib/safe_memoize/version.rb

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

data/lib/safe_memoize.rb

@@ -1,70 +1,24 @@
 # frozen_string_literal: true
 
 require_relative "safe_memoize/version"
+require_relative "safe_memoize/class_methods"
+require_relative "safe_memoize/public_methods"
+require_relative "safe_memoize/cache_store_methods"
+require_relative "safe_memoize/cache_record_methods"
+require_relative "safe_memoize/inspection_methods"
+require_relative "safe_memoize/hooks_methods"
+require_relative "safe_memoize/cache_metrics_methods"
+require_relative "safe_memoize/public_metrics_methods"
+require_relative "safe_memoize/custom_key_methods"
+require_relative "safe_memoize/public_custom_key_methods"
+require_relative "safe_memoize/instance_methods"
 
 module SafeMemoize
   class Error < StandardError; end
 
+  include InstanceMethods
+
   def self.prepended(base)
     base.extend(ClassMethods)
   end
-
-  module ClassMethods
-    def memoize(method_name)
-      method_name = method_name.to_sym
-
-      mod = Module.new do
-        define_method(method_name) do |*args, **kwargs, &block|
-          # Blocks bypass cache entirely — they aren't comparable
-          return super(*args, **kwargs, &block) if block
-
-          cache_key = [method_name, args, kwargs]
-
-          @__safe_memo_mutex__ ||= Mutex.new
-
-          # Fast path: check without lock
-          if defined?(@__safe_memo_cache__) && @__safe_memo_cache__.key?(cache_key)
-            return @__safe_memo_cache__[cache_key]
-          end
-
-          # Slow path: lock and double-check
-          @__safe_memo_mutex__.synchronize do
-            @__safe_memo_cache__ ||= {}
-
-            if @__safe_memo_cache__.key?(cache_key)
-              @__safe_memo_cache__[cache_key]
-            else
-              @__safe_memo_cache__[cache_key] = super(*args, **kwargs)
-            end
-          end
-        end
-      end
-
-      prepend mod
-    end
-  end
-
-  def reset_memo(method_name)
-    method_name = method_name.to_sym
-
-    return unless defined?(@__safe_memo_cache__)
-
-    if defined?(@__safe_memo_mutex__) && @__safe_memo_mutex__
-      @__safe_memo_mutex__.synchronize do
-        @__safe_memo_cache__.delete_if { |key, _| key[0] == method_name }
-      end
-    else
-      @__safe_memo_cache__.delete_if { |key, _| key[0] == method_name }
-    end
-  end
-
-  def reset_all_memos
-    if defined?(@__safe_memo_mutex__) && @__safe_memo_mutex__
-      @__safe_memo_mutex__.synchronize do
-        @__safe_memo_cache__ = {}
-      end
-    else
-      @__safe_memo_cache__ = {}
-    end
-  end
 end

data/sig/safe_memoize.rbs

@@ -1,12 +1,133 @@
 module SafeMemoize
   VERSION: String
+  include InstanceMethods
 
-  def self.prepended: (Class base) -> void
+  type default_memo_key = [Symbol, Array[untyped], Hash[Symbol, untyped]]
+  type custom_memo_key = [Symbol, untyped]
+  type memo_key = default_memo_key | custom_memo_key
+  type memo_record = { value: untyped, expires_at: Float? }
+
+  @__safe_memo_cache__: Hash[memo_key, memo_record]?
+  @__safe_memo_mutex__: Mutex?
 
-  def reset_memo: (Symbol method_name) -> void
-  def reset_all_memos: () -> void
+  def self.prepended: (Class base) -> void
 
   module ClassMethods
-    def memoize: (Symbol | String method_name) -> void
+    def memoize: (Symbol | String method_name, ?ttl: Numeric?) -> void
+
+    private
+
+    def memoized_method_visibility: (Symbol method_name) -> Symbol
+  end
+
+  module PublicMethods
+    def memoized?: (Symbol | String method_name, *untyped args, **untyped kwargs) ?{ () -> untyped } -> bool
+    def memo_count: (*untyped method_name) -> Integer
+    def memo_keys: (*untyped method_name) -> Array[untyped]
+    def memo_values: (*untyped method_name) -> Array[untyped]
+    def on_memo_expire: { (memo_key cache_key, memo_record record) -> untyped } -> void
+    def on_memo_evict: { (memo_key cache_key, memo_record record) -> untyped } -> void
+    def clear_memo_hooks: (Symbol? hook_type) -> void
+    def reset_memo: (Symbol | String method_name, *untyped args, **untyped kwargs) -> void
+    def reset_all_memos: () -> void
+  end
+
+  module CacheStoreMethods
+    @__safe_memo_cache__: Hash[memo_key, memo_record]?
+    @__safe_memo_mutex__: Mutex?
+
+    private
+
+    def with_memo_lock: { () -> untyped } -> untyped
+    def memo_cache_or_nil: () -> Hash[memo_key, memo_record]?
+    def memo_cache_hit?: (memo_key cache_key) -> bool
+    def memo_cache_record: (memo_key cache_key) -> memo_record?
+    def memo_cache_read: (memo_key cache_key) -> untyped?
+    def memo_fetch_or_store: (memo_key cache_key) { () -> untyped } -> untyped
+    def memo_mutex!: () -> Mutex
+    def with_memo_cache: { (Hash[memo_key, memo_record] cache) -> untyped } -> untyped?
+  end
+
+  module CacheRecordMethods
+    private
+
+    def memo_ttl: (Numeric? ttl) -> Float?
+    def memo_expires_at: (Float? ttl) -> Float?
+    def memo_record: (untyped value, expires_at: Float?) -> memo_record
+    def memo_record_value: (memo_record record) -> untyped
+    def memo_record_live?: (memo_record? record) -> bool
+    def memo_prune_expired_entries!: (Hash[memo_key, memo_record] cache) -> void
+  end
+
+  module InspectionMethods
+    private
+
+    def safe_memo_scoped_method: (Array[untyped] method_name) -> Symbol?
+    def memo_matcher_for: (Symbol method_name, Array[untyped] args, Hash[Symbol, untyped] kwargs) -> untyped
+    def memo_entries_for: (Symbol? method_name) -> Array[untyped]
+    def safe_memo_count_for: (Symbol? method_name) -> Integer
+    def safe_memo_keys_for: (Symbol? method_name) -> Array[untyped]
+    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
+  end
+
+  module HooksMethods
+    @__safe_memo_hooks__: { on_expire: Array[Proc], on_evict: Array[Proc] }?
+
+    private
+
+    def memo_hook_store: () -> { on_expire: Array[Proc], on_evict: Array[Proc] }
+    def register_memo_hook: (Symbol hook_type) { (memo_key cache_key, memo_record record) -> untyped } -> void
+    def call_memo_hooks: (Symbol hook_type, memo_key cache_key, memo_record record) -> void
+    def _clear_memo_hooks: (Symbol? hook_type) -> void
+  end
+
+  module CacheMetricsMethods
+    @__safe_memo_metrics__: Hash[memo_key, { hits: Integer, misses: Integer, total_time: Float }]?
+
+    private
+
+    def memo_metrics_store: () -> Hash[memo_key, { hits: Integer, misses: Integer, total_time: Float }]
+    def record_cache_hit: (Symbol method_name, Array[untyped] args) -> void
+    def record_cache_miss: (Symbol method_name, Array[untyped] args, Float computation_time) -> void
+    def _reset_cache_metrics: () -> void
+  end
+
+  module PublicMetricsMethods
+    def cache_stats: () -> Hash[Symbol, untyped]
+    def cache_stats_for: (Symbol | String method_name) -> Hash[Symbol, untyped]
+    def cache_hit_rate: () -> Float
+    def cache_miss_rate: () -> Float
+    def cache_metrics_reset: () -> void
+  end
+
+  module CustomKeyMethods
+    @__safe_memo_custom_keys__: Hash[Symbol, Proc]?
+
+    private
+
+    def custom_key_store: () -> Hash[Symbol, Proc]
+    def register_custom_key: (Symbol | String method_name) { (*untyped args, **untyped kwargs) -> untyped } -> void
+    def compute_cache_key: (Symbol | String method_name, Array[untyped] args, Hash[Symbol, untyped] kwargs) -> memo_key
+    def _clear_custom_keys: () -> void
+  end
+
+  module PublicCustomKeyMethods
+    def memoize_with_custom_key: (Symbol | String method_name) { (*untyped args, **untyped kwargs) -> untyped } -> void
+    def clear_custom_keys: (Symbol | String? method_name) -> void
+  end
+
+  module InstanceMethods
+    include PublicMethods
+    include CacheStoreMethods
+    include CacheRecordMethods
+    include InspectionMethods
+    include HooksMethods
+    include CacheMetricsMethods
+    include PublicMetricsMethods
+    include CustomKeyMethods
+    include PublicCustomKeyMethods
   end
 end
+

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: safe_memoize
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Chuck Smith
@@ -18,11 +18,25 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".github/workflows/ci.yml"
+- ".github/workflows/release.yml"
 - CHANGELOG.md
 - LICENSE.txt
 - README.md
 - Rakefile
 - lib/safe_memoize.rb
+- lib/safe_memoize/cache_metrics_methods.rb
+- lib/safe_memoize/cache_record_methods.rb
+- lib/safe_memoize/cache_store_methods.rb
+- lib/safe_memoize/class_methods.rb
+- lib/safe_memoize/custom_key_methods.rb
+- lib/safe_memoize/hooks_methods.rb
+- lib/safe_memoize/inspection_methods.rb
+- lib/safe_memoize/instance_methods.rb
+- lib/safe_memoize/public_custom_key_methods.rb
+- lib/safe_memoize/public_methods.rb
+- lib/safe_memoize/public_metrics_methods.rb
+- lib/safe_memoize/release_tooling.rb
 - lib/safe_memoize/version.rb
 - sig/safe_memoize.rbs
 homepage: https://github.com/eclectic-coding/safe_memoize
@@ -47,7 +61,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.2
+rubygems_version: 3.6.9
 specification_version: 4
 summary: Thread-safe memoization that correctly handles nil and false values
 test_files: []