bipolar_cache 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 14dba1b50e859c7210b98cc2fb557341169d4e97ca5e1e90cf82ed5eeb1a617f
-  data.tar.gz: 2a26dd62e0ee0cb66e8bc2d4821831850a56d4a212b6574dbde3cb8043dc817a
+  metadata.gz: 3bb404064cea70958b9164dce8ca19a2896ed8cceb9472af9e893a7d32a9ea83
+  data.tar.gz: 4cd2da217bb8347ea474949fc6a21d6accdb125e438f1091dbb746aa4c8ca4a3
 SHA512:
-  metadata.gz: e10eb1702dcdea29b43c149a6cc364ec8ec999ab45c1334fa931087af7700324ffad07a782e38fa72cad5fbc6d2231a98615bf454da73ce447fd5b9621cc6573
-  data.tar.gz: 21114e271dfec2fde22731c7ed81b24cd12fcc7286dbd5c4debda8be36f5a67ca795e99ce33629807cc3720b3f70b93fe54a203abbe0652cfd00dc74daa06a30
+  metadata.gz: 6c9ac5ae9a879b6e399a83f5a8ff8cdbdb4e7180917b52f40c60b9f38e2309c90f96e98cfe909e8e56527c40c94b76a0ffb3b09a2380aa4ab8f5213031069c5e
+  data.tar.gz: 5a1ee634187ad333b3d5d728d4e5cd957569f5806c4ffb1c666dbb066ec3884d484225ad36d856eb6fcc657bcd70ebf0fdcaba00ac9464662cd76c4070c3a7f3

data/.rubocop.yml

@@ -6,9 +6,19 @@ AllCops:
 Metrics/AbcSize:
   Enabled: false
 
+Metrics/CyclomaticComplexity:
+  Enabled: false
+
+Metrics/PerceivedComplexity:
+  Enabled: false
+
 Metrics/MethodLength:
   Enabled: false
 
+Metrics/ClassLength:
+  Exclude:
+    - "test/**/*"
+
 Style/Documentation:
   Enabled: false
 

data/CHANGELOG.md

@@ -0,0 +1,52 @@
+# Changelog
+
+## 0.5.0 - 2026-10-14
+
+### Breaking changes
+
+- `BipolarCache.read!` raises `ArgumentError` for missing, unknown or non-callable
+  keywords. Before, a missing `actual:` surfaced as a `NoMethodError` that `rescue:` swallowed,
+  and misspelled keywords were silently ignored.
+- `BipolarCache.read!`: when only the cache write fails, the error goes to `rescue:` (or is
+  re-raised without one) but the value that was read is still returned instead of the `rescue:` result.
+- Sequel plugin: procs passed to `bipolar_count_cache` run in the scope of the model instance
+  (`self` used to be the class), so they can call instance methods and associations directly.
+- Sequel plugin: for `Sequel::Model` instances the default cache write is a bare dataset `UPDATE`
+  of the cache column. It no longer runs validations and hooks, saves other unsaved columns or
+  inserts an unsaved record. `increment!`/`decrement!` use `coalesce(col, 0) + n` in SQL, so
+  concurrent increments are not lost and a `NULL` column is handled. Your own `update:` is
+  still called with the new value.
+- Sequel plugin: invalid options (wrong type, `chance` below 0, above 100 or `NaN`) raise
+  `ArgumentError` when `bipolar_count_cache` is declared instead of on first use.
+- Sequel plugin: the `bcsp_*` helper methods are private. `fetch_or_build_procs` is gone: procs are
+  built per call instead of being memoized on the instance.
+
+### Changed
+
+- `BipolarCache.read!`: `if:` is optional (default: caching enabled) and every
+  callable may be any object responding to `call`, not only a `Proc`.
+- Sequel plugin: `if:`, `chance:` and `rescue:` accept a Symbol/String naming an instance method,
+  like `actual:`, `cached:` and `update:` already did. `if: :method` used to be ignored,
+  which left caching switched on.
+
+### Fixed
+
+- Sequel plugin: two `bipolar_count_cache` declarations with the same association name no longer
+  share one set of procs.
+- Sequel plugin: a `dup`/`clone` no longer reads and writes the original record's cache.
+- Sequel plugin: reading a count on a frozen model no longer raises `FrozenError`.
+- Sequel plugin: `refresh!` goes through `rescue:` like `increment!`/`decrement!`, and those two
+  no longer replace the original error with a `NoMethodError`.
+- Sequel plugin: a model whose count was read can be `Marshal.dump`ed again. The memoized procs
+  lived in an instance variable and made `Marshal.dump` raise `TypeError`.
+- Sequel plugin: with the default `chance`, a `NULL` cache column is a miss. It used to be a hit 10% of
+  the time and `comments_count` returned `nil`.
+- Sequel plugin: the default cache write clears the cache column from `changed_columns`, so a later
+  `save`/`save_changes` no longer writes a stale value over a newer one.
+
+### Added
+
+- Type signatures in `sig/bipolar_cache.rbs`.
+- Tests against real `Sequel::Model` instances, both with Sequel's mock adapter and with an
+  in-memory SQLite database; `sequel` and `sqlite3` are development dependencies.
+- Ruby 4.0 in the CI matrix.

data/README.md

@@ -1,26 +1,167 @@
 # BipolarCache
 
-Probabalistic caching toolkit useful for caching of database counters, and other operations.
+Probabilistic caching toolkit for Ruby. Instead of always hitting the database or always returning a cached value, BipolarCache flips a coin — sometimes you get the cache, sometimes you get the real thing, and when the real thing differs, the cache gets updated.
+
+Useful for caching database counters and other operations where occasional staleness is acceptable and you want to gradually reduce database load without explicit cache invalidation.
+
+## How it works
+
+```
+BipolarCache.read!  →  should we cache?  (if)
+                          │
+                    no ────┘──── yes
+                    │              │
+               return actual    read cached value
+                                   │
+                              chance(cached) > rand?
+                                   │
+                             yes ──┘── no
+                             │         │
+                        return      compute actual
+                        cached         │
+                                  cached != actual?
+                                       │
+                                 yes ──┘── no
+                                 │         │
+                            update      return
+                            cache       actual
+                            return
+                            actual
+```
 
 ## Installation
 
-Install the gem and add to the application's Gemfile by executing:
+Add to your Gemfile:
 
-    $ bundle add bipolar_cache
+```ruby
+gem "bipolar_cache"
+```
 
-If bundler is not being used to manage dependencies, install the gem by executing:
+Or install directly:
 
-    $ gem install bipolar_cache
+```
+$ gem install bipolar_cache
+```
 
 ## Usage
 
+### Core API
 
+`BipolarCache.read!` accepts six keyword arguments, all callables (procs, lambdas, or anything that responds to `call`):
 
-## Development
+```ruby
+result = BipolarCache.read!(
+  actual: -> { Post.where(user_id: user.id).count },  # the real value (expensive)
+  cached: -> { user.posts_count_cache },               # the cached value (cheap)
+  chance: ->(cached_value) { cached_value < 10 ? 0.1 : 0.9 },  # probability of cache hit
+  if:     -> { user.caching_enabled? },                # enable/disable caching
+  update: ->(value) { user.update(posts_count_cache: value) },  # write new value to cache
+  rescue: ->(error) { Rails.logger.error(error); 0 }   # handle errors
+)
+```
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `actual`  | yes | Callable that returns the real value (e.g., a database query) |
+| `cached`  | yes | Callable that returns the cached value |
+| `chance`  | yes | Callable that receives the cached value and returns a float 0.0-1.0. Higher = more likely to use cache. |
+| `if`      | no  | Callable that returns true/false. When false, always returns the actual value. Defaults to always enabled. |
+| `update`  | yes | Callable that receives the actual value and persists it to the cache |
+| `rescue`  | no  | Callable that receives a `StandardError`. Without it, errors re-raise. |
+
+Missing, unknown (e.g. a misspelled `chnace:`) or non-callable arguments raise `ArgumentError`, even when `rescue` is given.
+
+#### Errors
+
+- An error while reading (`if`, `cached`, `chance` or `actual`) goes to `rescue`, and its return value becomes the result.
+- An error while writing the cache (`update`) is also passed to `rescue`, but the result is still the actual value
+  that was just read. A failed cache write never replaces a good answer.
+- Without `rescue`, both kinds of error are re-raised.
+
+### Sequel Plugin (alpha)
+
+For [Sequel](https://github.com/jeremyevans/sequel) models, the plugin generates all the procs automatically. Your model needs a `_count_cache` column (e.g., `comments_count_cache`):
+
+```ruby
+require "bipolar_cache/sequel/plugin_alpha"
+
+class User < Sequel::Model
+  include BipolarCache::Sequel::PluginAlpha
+
+  # Assumes:
+  #   - association: user.comments_dataset
+  #   - cache column: user.comments_count_cache
+  bipolar_count_cache :comments
+end
+```
+
+This generates four instance methods:
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+```ruby
+user.comments_count            # probabilistic: returns cached or actual count
+user.comments_count_refresh!   # force: computes actual and updates cache
+user.comments_count_increment! # bump cache by 1 (or by: n), returns the new value
+user.comments_count_decrement! # drop cache by 1 (or by: n), returns the new value
+```
+
+#### Options
+
+```ruby
+bipolar_count_cache :comments,
+  method: "comment_total",           # custom method name (default: "{name}_count")
+  chance: 75,                        # fixed probability as percentage (default: adaptive)
+  actual: -> { comments_dataset.where(visible: true).count },  # custom actual proc
+  cached: :my_cache_column,          # custom cache column/method name
+  update: ->(v) { update(my_cache_column: v) },  # custom update proc
+  rescue: ->(e) { log(e); nil },     # custom error handler
+  if: -> { !new? }                   # disable caching for unsaved records
+```
+
+Procs run in the scope of the model instance, so they can call its methods and associations directly.
+`actual`, `cached`, `update`, `if`, `chance` and `rescue` also accept a Symbol (or String) naming an
+instance method, which receives the same arguments the proc would:
+
+```ruby
+bipolar_count_cache :comments, if: :caching_enabled?, chance: :hit_chance, rescue: :report_error
+```
+
+Options are checked when `bipolar_count_cache` is declared: a value of the wrong type, or a numeric `chance`
+outside 0-100 (or `NaN`), raises `ArgumentError` at class-load time. A method name that the model doesn't
+respond to raises `ArgumentError` the first time the cache is used.
+
+#### How the cache is written
+
+For a `Sequel::Model` the default write is a plain `UPDATE` of the cache column. It does not run validations or
+hooks, does not save other unsaved changes on the record, and does nothing in the database for a record that
+isn't saved yet (the new value only lives in memory). `increment!` and `decrement!` are done in SQL
+(`cache = coalesce(cache, 0) + n`), so concurrent bumps don't overwrite each other and a `NULL` column counts as 0.
+
+Passing your own `update:` replaces all of this: it is called with the new value, whatever it does.
+
+By default errors are logged with `warn` and the method returns `0`; pass `rescue:` to change that.
+
+#### Chance values
+
+The `chance` option controls cache-hit probability:
+
+| Value | Interpretation | Example |
+|-------|---------------|---------|
+| `0.0` - `1.0` (Float) | Direct probability | `chance: 0.9` = 90% cache hit |
+| `1` (Integer) | Direct probability (1.0 = 100%) | `chance: 1` = always cache |
+| `2` - `100` (Integer) | Percentage, divided by 100 | `chance: 75` = 75% cache hit |
+| `0` | Never use cache | `chance: 0` = always compute actual |
+| Proc | Dynamic, receives cached value | `chance: ->(v) { v > 100 ? 0.95 : 0.5 }` |
+| _(omitted)_ | Adaptive default | < 10: 10% cache hit, >= 10: 90% cache hit |
+
+## Development
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+```
+bin/setup          # install dependencies
+rake test          # run tests
+rake rubocop       # lint
+rake               # run both
+bin/console        # interactive prompt
+```
 
 ## Contributing
 

data/lib/bipolar_cache/sequel/plugin_alpha.rb

@@ -1,143 +1,224 @@
 # frozen_string_literal: true
 
+require_relative "../../bipolar_cache"
+
 module BipolarCache
+  # NOTE: inside this namespace a bare +Sequel+ is BipolarCache::Sequel;
+  # reach the gem with +::Sequel+.
   module Sequel
     module PluginAlpha
       module ClassMethods
         def bipolar_count_cache(name, **opts)
+          Options.validate!(opts)
           opts = opts.merge({ name: name })
           method_name = opts[:method] || "#{name}_count"
 
           define_method method_name do
-            bcsp_cache(**fetch_or_build_procs(**opts))
+            bcsp_cache(**bcsp_build_procs(**opts))
           end
 
           define_method "#{method_name}_refresh!" do
-            procs = fetch_or_build_procs(**opts)
-            actual_value = procs[:actual].call
-            procs[:update].call(actual_value) if actual_value != procs[:cached].call
-            actual_value
+            procs = bcsp_build_procs(**opts)
+
+            bcsp_guarded(procs) do
+              actual_value = procs[:actual].call
+              procs[:update].call(actual_value) if actual_value != procs[:cached].call
+              actual_value
+            end
           end
 
           define_method "#{method_name}_increment!" do |by: 1|
-            procs = fetch_or_build_procs(**opts)
-
-            procs[:update].call(by + procs[:cached].call)
+            bcsp_adjust_cache!(opts, by)
           end
 
           define_method "#{method_name}_decrement!" do |by: 1|
-            procs = fetch_or_build_procs(**opts)
-
-            procs[:update].call((-by) + procs[:cached].call)
+            bcsp_adjust_cache!(opts, -by)
           end
         end
       end
 
-      def self.included(base)
-        base.extend ClassMethods
-      end
+      module Options
+        class << self
+          # Checks everything about the options that can be checked without an
+          # instance, so a bad declaration fails when the class is loaded.
+          def validate!(opts)
+            %i[actual cached update if rescue chance].each { |key| validate_option!(key, opts[key]) }
+          end
 
-      def bcsp_cache(**procs)
-        BipolarCache.read!(**procs)
+          # Turns a numeric chance into a probability: 0..1 is taken as is,
+          # anything above 1 is a percentage.
+          def chance_probability(chance)
+            raise ArgumentError, "chance must be a number, got NaN" if chance.is_a?(Float) && chance.nan?
+            raise ArgumentError, "chance must be >= 0, got #{chance}" if chance.negative?
+            raise ArgumentError, "chance must be <= 100, got #{chance}" if chance > 100
+
+            chance > 1 ? chance / 100.0 : chance
+          end
+
+          private
+
+          def validate_option!(key, value)
+            return if value.nil? || value.is_a?(Proc) || value.is_a?(Symbol) || value.is_a?(String)
+            return if key == :if && [true, false].include?(value)
+            return chance_probability(value) if key == :chance && (value.is_a?(Integer) || value.is_a?(Float))
+
+            raise ArgumentError, "#{key} has an unsupported value: #{value.inspect}"
+          end
+        end
       end
 
-      def fetch_or_build_procs(**opts)
-        # create cached store for instance procs, if none
-        instance_variable_set(:@bcsp_proc_store, {}) unless instance_variable_defined?(:@bcsp_proc_store)
-
-        if instance_variable_get(:@bcsp_proc_store)[opts[:name]].nil?
-          instance_variable_get(:@bcsp_proc_store)[opts[:name]] =
-            {
-              actual: bcsp_proc_actual_from(**opts),
-              cached: bcsp_proc_cached_from(**opts),
-              update: bcsp_proc_update_from(**opts),
-              chance: bcsp_proc_chance_from(**opts),
-              rescue: bcsp_proc_rescue_from(**opts),
-              if: bcsp_proc_if_from(**opts)
-            }
+      # Turns the declaration options into the callables BipolarCache.read!
+      # expects, all bound to the instance they are built on.
+      module Builders
+        private
+
+        def bcsp_build_procs(**opts)
+          {
+            actual: bcsp_proc_actual_from(**opts),
+            cached: bcsp_proc_cached_from(**opts),
+            update: bcsp_proc_update_from(**opts),
+            chance: bcsp_proc_chance_from(**opts),
+            rescue: bcsp_proc_rescue_from(**opts),
+            if: bcsp_proc_if_from(**opts)
+          }.freeze
         end
 
-        # stored procs
-        instance_variable_get(:@bcsp_proc_store)[opts[:name]]
-      end
+        # Procs run in the scope of the instance; Symbols and Strings name a
+        # method of the instance that receives the call arguments.
+        def bcsp_bind(key, option)
+          case option
+          when Proc
+            ->(*args) { instance_exec(*args, &option) }
+          when Symbol, String
+            unless respond_to?(option, true)
+              raise ArgumentError, "#{key}: #{option.inspect} is not a method of #{self.class} " \
+                                   "(expected a Proc or the name of an instance method)"
+            end
+
+            ->(*args) { send(option, *args) }
+          else
+            raise ArgumentError, "#{key} must be a Proc, Symbol or String, got #{option.inspect}"
+          end
+        end
+
+        def bcsp_proc_actual_from(**opts)
+          return bcsp_bind(:actual, opts[:actual]) unless opts[:actual].nil?
 
-      def bcsp_proc_actual_from(**opts)
-        case opts[:actual]
-        when Proc
-          opts[:actual]
-        when String, Symbol
-          -> { send(opts[:actual]) }
-        else
           -> { send("#{opts[:name]}_dataset").count }
         end
-      end
 
-      def bcsp_proc_cached_from(**opts)
-        case opts[:cached]
-        when Proc
-          opts[:cached]
-        when String, Symbol
-          -> { send(opts[:cached]) }
-        else
+        def bcsp_proc_cached_from(**opts)
+          return bcsp_bind(:cached, opts[:cached]) unless opts[:cached].nil?
+
           -> { send("#{opts[:name]}_count_cache") }
         end
-      end
 
-      def bcsp_proc_update_from(**opts)
-        cache_name = if opts[:cached].is_a?(String) || opts[:cached].is_a?(Symbol)
-                       opts[:cached]
-                     else
-                       "#{opts[:name]}_count_cache"
-                     end
-
-        case opts[:update]
-        when Proc
-          opts[:update]
-        when String, Symbol
-          -> { send(opts[:update]) }
-        else
-          ->(value) { update({ cache_name => value }) }
+        def bcsp_proc_update_from(**opts)
+          return bcsp_bind(:update, opts[:update]) unless opts[:update].nil?
+
+          column = bcsp_cache_column(opts)
+          ->(value) { bcsp_write_cache(column, value) }
         end
-      end
 
-      def bcsp_proc_chance_from(**opts)
-        case opts[:chance]
-        when Proc
-          opts[:chance]
-        when Integer, Float
-          normalised_chance = if opts[:chance] > 1
-                                opts[:chance] / 100
-                              else
-                                opts[:chance]
-                              end
-          ->(_value) { normalised_chance }
-        else # default
-          ->(value) { value < 10 ? 0.1 : 0.9 }
+        def bcsp_proc_chance_from(**opts)
+          case opts[:chance]
+          when nil # default
+            lambda { |value|
+              next 0 if value.nil? # a missing cache is never a hit: it would hand back nil
+
+              value < 10 ? 0.1 : 0.9
+            }
+          when Integer, Float
+            probability = Options.chance_probability(opts[:chance])
+            ->(_value) { probability }
+          else
+            bcsp_bind(:chance, opts[:chance])
+          end
         end
-      end
 
-      def bcsp_proc_rescue_from(**opts)
-        if opts[:rescue].is_a? Proc
-          opts[:rescue]
-        else # default
+        def bcsp_proc_rescue_from(**opts)
+          return bcsp_bind(:rescue, opts[:rescue]) unless opts[:rescue].nil?
+
           lambda { |e|
-            e.inspect
+            warn "[BipolarCache] #{e.class}: #{e.message}"
             0
           }
         end
+
+        def bcsp_proc_if_from(**opts)
+          case opts[:if]
+          when nil # default
+            -> { true }
+          when true, false
+            value = opts[:if]
+            -> { value }
+          else
+            bcsp_bind(:if, opts[:if])
+          end
+        end
+
+        def bcsp_cache_column(opts)
+          case opts[:cached]
+          when String, Symbol then opts[:cached].to_sym
+          else :"#{opts[:name]}_count_cache"
+          end
+        end
+      end
+
+      include Builders
+
+      def self.included(base)
+        base.extend ClassMethods
+      end
+
+      private
+
+      def bcsp_cache(**procs)
+        BipolarCache.read!(**procs)
+      end
+
+      def bcsp_guarded(procs)
+        yield
+      rescue StandardError => e
+        procs[:rescue].call(e)
       end
 
-      def bcsp_proc_if_from(**opts)
-        case opts[:if]
-        when Proc
-          opts[:if]
-        when TrueClass, FalseClass
-          value = opts[:if]
-          -> { value }
-        else # default
-          -> { true }
+      def bcsp_adjust_cache!(opts, delta)
+        procs = bcsp_build_procs(**opts)
+
+        bcsp_guarded(procs) do
+          new_value = (procs[:cached].call || 0) + delta
+
+          if opts[:update].nil? && bcsp_sequel_model?
+            column = bcsp_cache_column(opts)
+            relative = ::Sequel.function(:coalesce, ::Sequel[column], 0) + delta
+            bcsp_write_cache(column, new_value, relative)
+          else
+            procs[:update].call(new_value)
+          end
+
+          new_value
         end
       end
+
+      def bcsp_sequel_model?
+        defined?(::Sequel::Model) && is_a?(::Sequel::Model)
+      end
+
+      # Default cache writer. A Sequel model gets a bare UPDATE of the cache
+      # column: no validations, hooks or other unsaved columns are involved,
+      # and +expression+ lets the database do the arithmetic. Anything else
+      # is asked to #update itself.
+      def bcsp_write_cache(column, value, expression = value)
+        return update({ column => value }) unless bcsp_sequel_model?
+
+        this.update(column => expression) unless new?
+        return if frozen?
+
+        values[column] = value
+        # the value is now in the database; a later save must not write it again
+        changed_columns.delete(column)
+      end
     end
   end
 end

data/lib/bipolar_cache/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module BipolarCache
-  VERSION = "0.3.0"
+  VERSION = "0.5.0"
 end

data/lib/bipolar_cache.rb

@@ -1,11 +1,15 @@
 # frozen_string_literal: true
 
 require_relative "bipolar_cache/version"
-require_relative "bipolar_cache/sequel/plugin_alpha"
 
 module BipolarCache
   class Error < StandardError; end
 
+  REQUIRED_KEYS = %i[actual cached chance update].freeze
+  OPTIONAL_KEYS = %i[if rescue].freeze
+  ALWAYS = -> { true }
+  private_constant :REQUIRED_KEYS, :OPTIONAL_KEYS, :ALWAYS
+
   ##
   # It may read actual value,
   # it may read cached value,
@@ -13,27 +17,60 @@ module BipolarCache
   # It depends on chance.
   # Call it at your peril.
   #
-  # @param actual [Proc] callable to perform an operation (cacheable)
-  # @param cached [Proc] callable to read cached value
-  # @param chance [Proc(Object)] callable to compute chance of cache hit
-  # @param if     [Proc] callable to enable/disable caching
-  # @param rescue [Proc(StandardError)] callable to be invoked on exception
-  # @param update [Proc(Object)] callable to update cached value
+  # Errors raised while reading are passed to +rescue+ (re-raised without it).
+  # An error raised while writing the cache is reported to +rescue+ the same
+  # way, but the value that was read is still returned.
+  #
+  # @param actual [#call] callable to perform an operation (cacheable)
+  # @param cached [#call] callable to read cached value
+  # @param chance [#call(Object)] callable to compute chance of cache hit
+  # @param if     [#call] callable to enable/disable caching (default: enabled)
+  # @param rescue [#call(StandardError)] callable to be invoked on exception
+  # @param update [#call(Object)] callable to update cached value
   # @return [Object]
+  # @raise [ArgumentError] on missing, unknown or non-callable arguments
   def self.read!(**procs)
-    return procs[:actual].call unless procs[:if].call
+    procs = normalize!(procs)
+    rescuer = procs[:rescue]
 
-    cached_value = procs[:cached].call
+    begin
+      return procs[:actual].call unless procs[:if].call
+
+      cached_value = procs[:cached].call
+      return cached_value if procs[:chance].call(cached_value) > rand
 
-    if procs[:chance].call(cached_value) > rand
-      cached_value
-    else
       actual_value = procs[:actual].call
+    rescue StandardError => e
+      raise unless rescuer
+
+      return rescuer.call(e)
+    end
+
+    begin
       procs[:update].call(actual_value) if cached_value != actual_value
+    rescue StandardError => e
+      raise unless rescuer
+
+      rescuer.call(e)
+    end
+
+    actual_value
+  end
+
+  def self.normalize!(procs)
+    procs = procs.compact
 
-      actual_value
+    unknown = procs.keys - REQUIRED_KEYS - OPTIONAL_KEYS
+    raise ArgumentError, "unknown keywords: #{unknown.map(&:inspect).join(", ")}" unless unknown.empty?
+
+    missing = REQUIRED_KEYS - procs.keys
+    raise ArgumentError, "missing keywords: #{missing.map(&:inspect).join(", ")}" unless missing.empty?
+
+    procs.each do |key, callable|
+      raise ArgumentError, "#{key} must respond to #call, got #{callable.inspect}" unless callable.respond_to?(:call)
     end
-  rescue StandardError => e
-    procs[:rescue].call(e) if procs[:rescue].is_a?(Proc)
+
+    { if: ALWAYS }.merge(procs)
   end
+  private_class_method :normalize!
 end

data/sig/bipolar_cache.rbs

@@ -1,4 +1,50 @@
 module BipolarCache
   VERSION: String
-  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+
+  class Error < StandardError
+  end
+
+  interface _Call
+    def call: () -> untyped
+  end
+
+  interface _CallWithValue
+    def call: (untyped value) -> untyped
+  end
+
+  interface _CallWithError
+    def call: (StandardError error) -> untyped
+  end
+
+  def self.read!: (
+    actual: _Call,
+    cached: _Call,
+    chance: _CallWithValue,
+    update: _CallWithValue,
+    ?if: _Call?,
+    ?rescue: _CallWithError?
+  ) -> untyped
+
+  module Sequel
+    module PluginAlpha
+      # A Proc runs in the scope of the model instance; a Symbol or String
+      # names an instance method that receives the call arguments.
+      type callable = Proc | Symbol | String
+
+      def self.included: (Module base) -> void
+
+      module ClassMethods
+        def bipolar_count_cache: (
+          Symbol | String name,
+          ?method: Symbol | String,
+          ?actual: callable?,
+          ?cached: callable?,
+          ?update: callable?,
+          ?chance: callable | Integer | Float | nil,
+          ?if: callable | bool | nil,
+          ?rescue: callable?
+        ) -> void
+      end
+    end
+  end
 end

metadata

@@ -1,16 +1,15 @@
 --- !ruby/object:Gem::Specification
 name: bipolar_cache
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Andriy Tyurnikov
-autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-04-11 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
-description: Probabalistic caching toolkit useful for caching of database counters,
+description: Probabilistic caching toolkit useful for caching of database counters,
   and other operations.
 email:
 - Andriy.Tyurnikov@gmail.com
@@ -19,6 +18,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".rubocop.yml"
+- CHANGELOG.md
 - README.md
 - Rakefile
 - lib/bipolar_cache.rb
@@ -29,9 +29,8 @@ homepage: https://github.com/rubakas/bipolar_cache
 licenses: []
 metadata:
   homepage_uri: https://github.com/rubakas/bipolar_cache
-  source_code_uri: https://github.com/rubakas/bipolar_cache
-  changelog_uri: https://github.com/rubakas/bipolar_cache
-post_install_message:
+  source_code_uri: https://github.com/rubakas/bipolar_cache/tree/main
+  changelog_uri: https://github.com/rubakas/bipolar_cache/blob/main/CHANGELOG.md
 rdoc_options: []
 require_paths:
 - lib
@@ -46,8 +45,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.6
-signing_key:
+rubygems_version: 4.0.20
 specification_version: 4
-summary: BipolarCache. Probabalistic caching toolkit.
+summary: BipolarCache. Probabilistic caching toolkit.
 test_files: []