safe_memoize 0.1.0 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4806562a18a6f5143379d638d270ea3552280637dd33ed322c0f667f1257d836
-  data.tar.gz: bdb12e7ae3a41d230c85fd24750edcc5eeba4d90cf2ac93b59cd0bccc8ba0325
+  metadata.gz: 00d20095844739078f88cd287d4389b749f9953b9b6055939d733f2da139c19d
+  data.tar.gz: 5c4336dbe5e3ee1e1e2b822b92a3abd4f6d5452dedd36d99706c54eb8528ed7a
 SHA512:
-  metadata.gz: 4799eb0209980d5fee072ae05ff1661d70b8db5869e8701cac3fcd9241c1106f17fa84a798f85bcb084c197c24c646e2996fe60fa7375d4db8d780ad3bc4b71a
-  data.tar.gz: 6d64a7e4bef4d5b3825d903294bc955c1ec483157aee479496e001cb500e6128804e148791793d862938543bf5e9e7ee05cca128adb4bb37e68a9d4858bcb517
+  metadata.gz: 5d14486d2a280e2e243e2c54184875d175447f8dc921ff9e152374e9f8327061b0b4ce6de0e9213871000c0950a8cab146db7d303a0de8242d081c30e54c53ce
+  data.tar.gz: 67be0eb15e01782f7dc6b0a35cb79c24677f8d56ebf042a9dfdd49d9ec88a44c08711af24063150688c0b1ad9047c70a6c3754fd1cc662ba54a83000c1c5247a

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,18 @@
 ## [Unreleased]
 
+## [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,12 @@ 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
 - Block arguments bypass cache (blocks aren't comparable)
 
 ## Installation
@@ -94,12 +100,51 @@ 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
+```
+
+### 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 +155,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/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.1.2"
 end

data/lib/safe_memoize.rb

@@ -12,59 +12,195 @@ module SafeMemoize
   module ClassMethods
     def memoize(method_name)
       method_name = method_name.to_sym
+      visibility = memoized_method_visibility(method_name)
 
       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
+          cache_key = safe_memo_cache_key(method_name, args, kwargs)
 
           # 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
+          return memo_cache_read(cache_key) if memo_cache_hit?(cache_key)
+
+          memo_fetch_or_store(cache_key) { super(*args, **kwargs) }
         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
 
-  def reset_memo(method_name)
+  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
+      with_memo_cache { |cache| cache.key?(cache_key) } || false
+    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 reset_memo(method_name, *args, **kwargs)
     method_name = method_name.to_sym
 
-    return unless defined?(@__safe_memo_cache__)
+    matcher = memo_matcher_for(method_name, args, kwargs)
 
-    if defined?(@__safe_memo_mutex__) && @__safe_memo_mutex__
-      @__safe_memo_mutex__.synchronize do
-        @__safe_memo_cache__.delete_if { |key, _| key[0] == method_name }
+    with_memo_lock do
+      with_memo_cache do |cache|
+        cache.delete_if { |key, _| matcher.call(key) }
       end
-    else
-      @__safe_memo_cache__.delete_if { |key, _| key[0] == method_name }
     end
   end
 
   def reset_all_memos
+    with_memo_lock do
+      @__safe_memo_cache__ = {}
+    end
+  end
+
+  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 with_memo_lock
     if defined?(@__safe_memo_mutex__) && @__safe_memo_mutex__
-      @__safe_memo_mutex__.synchronize do
-        @__safe_memo_cache__ = {}
+      @__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)
+    cache = memo_cache_or_nil
+    cache&.key?(cache_key)
+  end
+
+  def memo_cache_read(cache_key)
+    cache = memo_cache_or_nil
+    cache && cache[cache_key]
+  end
+
+  def memo_fetch_or_store(cache_key)
+    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] = yield
       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
+
+  def memo_matcher_for(method_name, args, kwargs)
+    if args.empty? && kwargs.empty?
+      ->(key) { key[0] == method_name }
     else
-      @__safe_memo_cache__ = {}
+      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
+
+    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] = value if include_value
+    payload
+  end
+
+  def safe_memo_cache_key(method_name, args, kwargs)
+    [method_name.to_sym, args, kwargs]
+  end
 end

data/sig/safe_memoize.rbs

@@ -1,12 +1,47 @@
 module SafeMemoize
   VERSION: String
 
+  type memo_key = [Symbol, Array[untyped], Hash[Symbol, untyped]]
+  type memo_entry = [memo_key, untyped]
+
+  @__safe_memo_cache__: Hash[memo_key, untyped]?
+  @__safe_memo_mutex__: Mutex?
+
   def self.prepended: (Class base) -> void
 
-  def reset_memo: (Symbol method_name) -> void
+  def memoized?: (Symbol | String method_name, *untyped args, **untyped kwargs) -> bool
+  def memo_count: () -> Integer
+  def memo_count: (Symbol | String method_name) -> Integer
+  def memo_keys: () -> Array[untyped]
+  def memo_keys: (Symbol | String method_name) -> Array[untyped]
+  def memo_values: () -> Array[untyped]
+  def memo_values: (Symbol | String method_name) -> Array[untyped]
+  def reset_memo: (Symbol | String method_name, *untyped args, **untyped kwargs) -> void
   def reset_all_memos: () -> void
 
+  private
+
+  def safe_memo_scoped_method: (Array[untyped] method_name) -> Symbol?
+  def with_memo_lock: { () -> untyped } -> untyped
+  def memo_cache_or_nil: () -> Hash[memo_key, untyped]?
+  def memo_cache_hit?: (memo_key cache_key) -> bool
+  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, untyped] cache) -> untyped } -> untyped?
+  def memo_matcher_for: (Symbol method_name, Array[untyped] args, Hash[Symbol, untyped] kwargs) -> ((memo_key) -> bool)
+  def memo_entries_for: (Symbol? method_name) -> Array[memo_entry]
+  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, untyped 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) -> memo_key
+
   module ClassMethods
     def memoize: (Symbol | String method_name) -> void
+
+    private
+
+    def memoized_method_visibility: (Symbol method_name) -> (:private | :protected | :public)
   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.1.2
 platform: ruby
 authors:
 - Chuck Smith
@@ -18,11 +18,14 @@ 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/release_tooling.rb
 - lib/safe_memoize/version.rb
 - sig/safe_memoize.rbs
 homepage: https://github.com/eclectic-coding/safe_memoize
@@ -47,7 +50,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: []