Forward keyword arguments and blocks through cached methods

Generated methods only accepted *args, silently dropping keyword
arguments and blocks. This caused methods with kwargs to break
when wrapped with `cacheable`.

Changes:
- All generated methods now accept *args, **kwargs, &block
- key_format procs receive kwargs as well
- unless proc is resolved once at definition time instead of per-call
- Use Bundler.setup instead of Bundler.require in spec_helper for
  Ruby 4.0 compatibility

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: agrberg

README.md

@@ -155,12 +155,13 @@ require 'net/http'
 class GitHubApiAdapter
   include Cacheable
 
-  cacheable :star_count, key_format: ->(target, method_name, method_args) do
-    [target.class, method_name, method_args.first, Time.now.strftime('%Y-%m-%d')].join('/')
+  cacheable :star_count, key_format: ->(target, method_name, method_args, **kwargs) do
+    date = kwargs.fetch(:date, Time.now.strftime('%Y-%m-%d'))
+    [target.class, method_name, method_args.first, date].join('/')
   end
 
-  def star_count(repo)
-    puts "Fetching data from GitHub for #{repo}"
+  def star_count(repo, date: Time.now.strftime('%Y-%m-%d'))
+    puts "Fetching data from GitHub for #{repo} (as of #{date})"
     url = "https://api.github.com/repos/splitwise/#{repo}"
 
     JSON.parse(Net::HTTP.get(URI.parse(url)))['stargazers_count']
@@ -170,33 +171,34 @@ end
 
 * `target` is the object the method is being called on (`#<GitHubApiAdapter:0x0…0>`)
 * `method_name` is the name of the method being cached (`:star_count`)
-* `method_args` is an array of arguments being passed to the method (`[params]`)
+* `method_args` is an array of positional arguments being passed to the method (`[params]`)
+* `**kwargs` are the keyword arguments being passed to the method
 
 Including the method argument(s) allows you to cache different calls to the same method. Without the arguments in the cache key, a call to `star_count('cacheable')` would populate the cache and `star_count('tokenautocomplete')` would return the number of stars for Cacheable instead of what you want.
 
-In addition, we're including the current date in the cache key so calling this method tomorrow will return an updated value.
+**Note:** The `key_format` proc only receives keyword arguments that the caller explicitly passes — method defaults are not included. That's why the proc uses `kwargs.fetch(:date, Time.now.strftime('%Y-%m-%d'))` to compute its own default when `date:` is omitted. This ensures the cache key always varies by date.
 
 ```irb
 > a = GitHubApiAdapter.new
 > a.star_count('cacheable')
-Fetching data from GitHub for cacheable
- => 19
+Fetching data from GitHub for cacheable (as of 2026-02-26)
+ => 58
 > a.star_count('cacheable')
- => 19
+ => 58
 > a.star_count('tokenautocomplete')
-Fetching data from GitHub for tokenautocomplete
- => 1164
+Fetching data from GitHub for tokenautocomplete (as of 2026-02-26)
+ => 1309
 > a.star_count('tokenautocomplete')
- => 1164
+ => 1309
 
  # In this example the follow cache keys are generated:
- # GitHubApiAdapter/star_count/cacheable/2018-09-21
- # GitHubApiAdapter/star_count/tokenautocomplete/2018-09-21
+ # GitHubApiAdapter/star_count/cacheable/2026-02-26
+ # GitHubApiAdapter/star_count/tokenautocomplete/2026-02-26
 ```
 
 ### Conditional Caching
 
-You can control if a method should be cached by supplying a proc to the `unless:` option which will get the same arguments as `key_format:`. This logic can be defined in a method on the class and the name of the method as a symbol can be passed as well. **Note**: When using a symbol, the first argument, `target`, will not be passed but will be available as `self`.
+You can control if a method should be cached by supplying a proc to the `unless:` option which will get the same arguments as `key_format:` (`target, method_name, method_args, **kwargs`). This logic can be defined in a method on the class and the name of the method as a symbol can be passed as well. **Note**: When using a symbol, the first argument, `target`, will not be passed but will be available as `self`.
 
 ```ruby
 # From examples/conditional_example.rb
@@ -208,18 +210,19 @@ require 'net/http'
 class GitHubApiAdapter
   include Cacheable
 
-  cacheable :star_count, unless: :growing_fast?, key_format: ->(target, method_name, method_args) do
-    [target.class, method_name, method_args.first].join('/')
+  cacheable :star_count, unless: :growing_fast?, key_format: ->(target, method_name, method_args, **kwargs) do
+    date = kwargs.fetch(:date, Time.now.strftime('%Y-%m-%d'))
+    [target.class, method_name, method_args.first, date].join('/')
   end
 
-  def star_count(repo)
-    puts "Fetching data from GitHub for #{repo}"
+  def star_count(repo, date: Time.now.strftime('%Y-%m-%d'))
+    puts "Fetching data from GitHub for #{repo} (as of #{date})"
     url = "https://api.github.com/repos/splitwise/#{repo}"
 
     JSON.parse(Net::HTTP.get(URI.parse(url)))['stargazers_count']
   end
 
-  def growing_fast?(_method_name, method_args)
+  def growing_fast?(_method_name, method_args, **)
     method_args.first == 'cacheable'
   end
 end
@@ -230,17 +233,17 @@ Cacheable is new so we don't want to cache the number of stars it has as we expe
 ```irb
 > a = GitHubApiAdapter.new
 > a.star_count('tokenautocomplete')
-Fetching data from GitHub for tokenautocomplete
- => 1164
+Fetching data from GitHub for tokenautocomplete (as of 2026-02-26)
+ => 1309
 a.star_count('tokenautocomplete')
- => 1164
+ => 1309
 
 > a.star_count('cacheable')
-Fetching data from GitHub for cacheable
- => 19
+Fetching data from GitHub for cacheable (as of 2026-02-26)
+ => 58
 > a.star_count('cacheable')
-Fetching data from GitHub for cacheable
- => 19
+Fetching data from GitHub for cacheable (as of 2026-02-26)
+ => 58
 ```
 
 ### Cache Options

examples/conditional_example.rb

@@ -5,32 +5,33 @@
 class GitHubApiAdapter
   include Cacheable
 
-  cacheable :star_count, unless: :growing_fast?, key_format: ->(target, method_name, method_args) do
-    [target.class, method_name, method_args.first].join('/')
+  cacheable :star_count, unless: :growing_fast?, key_format: ->(target, method_name, method_args, **kwargs) do
+    date = kwargs.fetch(:date, Time.now.strftime('%Y-%m-%d'))
+    [target.class, method_name, method_args.first, date].join('/')
   end
 
-  def star_count(repo)
-    puts "Fetching data from GitHub for #{repo}"
+  def star_count(repo, date: Time.now.strftime('%Y-%m-%d'))
+    puts "Fetching data from GitHub for #{repo} (as of #{date})"
     url = "https://api.github.com/repos/splitwise/#{repo}"
 
     JSON.parse(Net::HTTP.get(URI.parse(url)))['stargazers_count']
   end
 
-  def growing_fast?(_method_name, method_args)
+  def growing_fast?(_method_name, method_args, **)
     method_args.first == 'cacheable'
   end
 end
 
 a = GitHubApiAdapter.new
 a.star_count('tokenautocomplete')
-# Fetching data from GitHub for tokenautocomplete
-# => 1164
+# Fetching data from GitHub for tokenautocomplete (as of 2026-02-26)
+# => 1309
 a.star_count('tokenautocomplete')
-# => 1164
+# => 1309
 
 a.star_count('cacheable')
-# Fetching data from GitHub for cacheable
-# => 19
+# Fetching data from GitHub for cacheable (as of 2026-02-26)
+# => 58
 a.star_count('cacheable')
-# Fetching data from GitHub for cacheable
-# => 19
+# Fetching data from GitHub for cacheable (as of 2026-02-26)
+# => 58

examples/custom_key_example.rb

@@ -5,12 +5,13 @@
 class GitHubApiAdapter
   include Cacheable
 
-  cacheable :star_count, key_format: ->(target, method_name, method_args) do
-    [target.class, method_name, method_args.first, Time.now.strftime('%Y-%m-%d')].join('/')
+  cacheable :star_count, key_format: ->(target, method_name, method_args, **kwargs) do
+    date = kwargs.fetch(:date, Time.now.strftime('%Y-%m-%d'))
+    [target.class, method_name, method_args.first, date].join('/')
   end
 
-  def star_count(repo)
-    puts "Fetching data from GitHub for #{repo}"
+  def star_count(repo, date: Time.now.strftime('%Y-%m-%d'))
+    puts "Fetching data from GitHub for #{repo} (as of #{date})"
     url = "https://api.github.com/repos/splitwise/#{repo}"
 
     JSON.parse(Net::HTTP.get(URI.parse(url)))['stargazers_count']
@@ -19,12 +20,12 @@ def star_count(repo)
 
 a = GitHubApiAdapter.new
 a.star_count('cacheable')
-# Fetching data from GitHub for cacheable
-# => 19
+# Fetching data from GitHub for cacheable (as of 2026-02-26)
+# => 58
 a.star_count('cacheable')
-# => 19
+# => 58
 a.star_count('tokenautocomplete')
-# Fetching data from GitHub for tokenautocomplete
-# => 1164
+# Fetching data from GitHub for tokenautocomplete (as of 2026-02-26)
+# => 1309
 a.star_count('tokenautocomplete')
-# => 1164
+# => 1309

lib/cacheable/method_generator.rb

@@ -20,41 +20,40 @@ def create_cacheable_methods(original_method_name, opts = {})
       method_names = create_method_names(original_method_name)
       key_format_proc = opts[:key_format] || default_key_format
 
+      unless_proc = opts[:unless].is_a?(Symbol) ? opts[:unless].to_proc : opts[:unless]
+
       const_get(method_interceptor_module_name).class_eval do
-        define_method(method_names[:key_format_method_name]) do |*args|
-          key_format_proc.call(self, original_method_name, args)
+        define_method(method_names[:key_format_method_name]) do |*args, **kwargs|
+          key_format_proc.call(self, original_method_name, args, **kwargs)
         end
 
-        define_method(method_names[:clear_cache_method_name]) do |*args|
-          Cacheable.cache_adapter.delete(__send__(method_names[:key_format_method_name], *args))
+        define_method(method_names[:clear_cache_method_name]) do |*args, **kwargs|
+          Cacheable.cache_adapter.delete(__send__(method_names[:key_format_method_name], *args, **kwargs))
         end
 
-        define_method(method_names[:without_cache_method_name]) do |*args|
-          original_method = method(original_method_name).super_method
-          original_method.call(*args)
+        define_method(method_names[:without_cache_method_name]) do |*args, **kwargs, &block|
+          method(original_method_name).super_method.call(*args, **kwargs, &block)
         end
 
-        define_method(method_names[:with_cache_method_name]) do |*args|
-          Cacheable.cache_adapter.fetch(__send__(method_names[:key_format_method_name], *args), opts[:cache_options]) do # rubocop:disable Lint/UselessDefaultValueArgument -- not Hash#fetch; second arg is cache options (e.g. expires_in) passed to the adapter
-            __send__(method_names[:without_cache_method_name], *args)
+        define_method(method_names[:with_cache_method_name]) do |*args, **kwargs, &block|
+          Cacheable.cache_adapter.fetch(__send__(method_names[:key_format_method_name], *args, **kwargs), opts[:cache_options]) do # rubocop:disable Lint/UselessDefaultValueArgument -- not Hash#fetch; second arg is cache options (e.g. expires_in) passed to the adapter
+            __send__(method_names[:without_cache_method_name], *args, **kwargs, &block)
           end
         end
 
-        define_method(original_method_name) do |*args|
-          unless_proc = opts[:unless].is_a?(Symbol) ? opts[:unless].to_proc : opts[:unless]
-
-          if unless_proc&.call(self, original_method_name, args)
-            __send__(method_names[:without_cache_method_name], *args)
+        define_method(original_method_name) do |*args, **kwargs, &block|
+          if unless_proc&.call(self, original_method_name, args, **kwargs)
+            __send__(method_names[:without_cache_method_name], *args, **kwargs, &block)
           else
-            __send__(method_names[:with_cache_method_name], *args)
+            __send__(method_names[:with_cache_method_name], *args, **kwargs, &block)
           end
         end
       end
     end
     # rubocop:enable Metrics/AbcSize, Metrics/MethodLength
 
     def default_key_format
-      proc do |target, method_name, _method_args|
+      proc do |target, method_name, _method_args, **_kwargs|
         # By default, we omit the _method_args from the cache key because there is no acceptable default behavior
         class_name = (target.is_a?(Module) ? target.name : target.class.name)
         cache_key = target.respond_to?(:cache_key) ? target.cache_key : class_name

spec/cacheable/cacheable_spec.rb

@@ -131,6 +131,73 @@
     end
   end
 
+  describe 'keyword arguments' do
+    it 'forwards keyword arguments to the original method' do
+      cacheable_class.class_eval do
+        define_method(:method_with_kwargs) do |name:, greeting: 'Hello'|
+          "#{greeting}, #{name}"
+        end
+
+        cacheable :method_with_kwargs, key_format: proc { |_, _, args, **kwargs| [args, kwargs] }
+      end
+
+      expect(cacheable_object.method_with_kwargs(name: 'World')).to eq('Hello, World')
+      expect(cacheable_object.method_with_kwargs(name: 'World', greeting: 'Hi')).to eq('Hi, World')
+    end
+
+    it 'forwards keyword arguments when skipping cache' do
+      cacheable_class.class_eval do
+        define_method(:kwargs_no_cache) do |val:|
+          val
+        end
+
+        cacheable :kwargs_no_cache, key_format: proc { |_, _, args, **kwargs| [args, kwargs] }
+      end
+
+      expect(cacheable_object.kwargs_no_cache_without_cache(val: 42)).to eq(42)
+    end
+
+    it 'forwards mixed positional and keyword arguments' do
+      cacheable_class.class_eval do
+        define_method(:mixed_args) do |pos, key:|
+          "#{pos}-#{key}"
+        end
+
+        cacheable :mixed_args, key_format: proc { |_, _, args, **kwargs| [args, kwargs] }
+      end
+
+      expect(cacheable_object.mixed_args('a', key: 'b')).to eq('a-b')
+    end
+  end
+
+  describe 'block forwarding' do
+    it 'forwards blocks to the original method on cache miss' do
+      cacheable_class.class_eval do
+        define_method(:method_with_block) do |&block|
+          block.call('from cache miss')
+        end
+
+        cacheable :method_with_block
+      end
+
+      result = cacheable_object.method_with_block { |msg| "got: #{msg}" }
+      expect(result).to eq('got: from cache miss')
+    end
+
+    it 'forwards blocks when skipping cache' do
+      cacheable_class.class_eval do
+        define_method(:block_no_cache) do |&block|
+          block.call('direct')
+        end
+
+        cacheable :block_no_cache
+      end
+
+      result = cacheable_object.block_no_cache_without_cache { |msg| "got: #{msg}" }
+      expect(result).to eq('got: direct')
+    end
+  end
+
   describe 'interceptor module' do
     it 'has the public generated methods' do
       expect(cacheable_class.ancestors.first.instance_methods(false)).to include(cacheable_method, :"#{cacheable_method}_without_cache", :"#{cacheable_method}_with_cache", :"#{cacheable_method}_key_format")
@@ -434,6 +501,20 @@ def cache_control_method
       expect(cacheable_object).to receive(inner_method).twice.and_call_original
       2.times { cacheable_object.send(cache_depends_on_args, the_method_arg) }
     end
+
+    it 'passes kwargs to the `unless` proc' do
+      cache_depends_on_kwargs = :cache_depends_on_kwargs
+      inner_method = cacheable_method_inner
+      cacheable_class.class_eval do
+        define_method(cache_depends_on_kwargs) do |force: false| # rubocop:disable Lint/UnusedBlockArgument
+          send inner_method
+        end
+
+        cacheable cache_depends_on_kwargs, unless: proc { |_, _, _, force: false| force }
+      end
+      expect(cacheable_object).to receive(inner_method).twice.and_call_original
+      2.times { cacheable_object.send(cache_depends_on_kwargs, force: true) }
+    end
   end
 
   describe 'on class methods' do

spec/spec_helper.rb

@@ -1,6 +1,4 @@
-require 'bundler'
-Bundler.require(:test)
-
+require 'bundler/setup'
 require 'cacheable'
 
 # This file was generated by the `rspec --init` command. Conventionally, all