bipolar_cache 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 14dba1b50e859c7210b98cc2fb557341169d4e97ca5e1e90cf82ed5eeb1a617f
-  data.tar.gz: 2a26dd62e0ee0cb66e8bc2d4821831850a56d4a212b6574dbde3cb8043dc817a
+  metadata.gz: 590637758a1d41dcf7614360ca6c2b3497030558a34832091d710e5938079bae
+  data.tar.gz: f1fe7e9f5644cab310a0239d521b40ad10286f33b802473f38f25ac09ba9a351
 SHA512:
-  metadata.gz: e10eb1702dcdea29b43c149a6cc364ec8ec999ab45c1334fa931087af7700324ffad07a782e38fa72cad5fbc6d2231a98615bf454da73ce447fd5b9621cc6573
-  data.tar.gz: 21114e271dfec2fde22731c7ed81b24cd12fcc7286dbd5c4debda8be36f5a67ca795e99ce33629807cc3720b3f70b93fe54a203abbe0652cfd00dc74daa06a30
+  metadata.gz: f2fbc688f2d14f886d03f64b85483ee09c8a23c400aba8c6d397aeb742887237c34b1de2d5b4702034a78e61204a6c76c76045be708c46069defe70375e0bdd6
+  data.tar.gz: b2ba003ac34a61e45c2a7b57b3e3a138f867b2751b49fe4dd87998865658d0ee9c0c15672e9c695459e2cfad2fefbfa061e8b84364e5f8beb62904be71eea098

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/README.md

@@ -1,26 +1,135 @@
 # 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):
 
-## 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`      | yes | Callable that returns true/false. When false, always returns the actual value. |
+| `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. |
+
+### 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
 
-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.
+  # Assumes:
+  #   - association: user.comments_dataset
+  #   - cache column: user.comments_count_cache
+  bipolar_count_cache :comments
+end
+```
+
+This generates four instance methods:
+
+```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)
+user.comments_count_decrement! # drop cache by 1 (or by: n)
+```
+
+#### 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) { set(my_col: v) },  # custom update proc
+  rescue: ->(e) { log(e); nil },     # custom error handler
+  if: -> { !new? }                   # disable caching for unsaved records
+```
+
+#### 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,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "../../bipolar_cache"
+
 module BipolarCache
   module Sequel
     module PluginAlpha
@@ -21,14 +23,24 @@ module BipolarCache
 
           define_method "#{method_name}_increment!" do |by: 1|
             procs = fetch_or_build_procs(**opts)
+            new_value = by + (procs[:cached].call || 0)
+            procs[:update].call(new_value)
+            new_value
+          rescue StandardError => e
+            raise unless procs[:rescue].is_a?(Proc)
 
-            procs[:update].call(by + procs[:cached].call)
+            procs[:rescue].call(e)
           end
 
           define_method "#{method_name}_decrement!" do |by: 1|
             procs = fetch_or_build_procs(**opts)
+            new_value = (-by) + (procs[:cached].call || 0)
+            procs[:update].call(new_value)
+            new_value
+          rescue StandardError => e
+            raise unless procs[:rescue].is_a?(Proc)
 
-            procs[:update].call((-by) + procs[:cached].call)
+            procs[:rescue].call(e)
           end
         end
       end
@@ -54,7 +66,7 @@ module BipolarCache
               chance: bcsp_proc_chance_from(**opts),
               rescue: bcsp_proc_rescue_from(**opts),
               if: bcsp_proc_if_from(**opts)
-            }
+            }.freeze
         end
 
         # stored procs
@@ -94,7 +106,7 @@ module BipolarCache
         when Proc
           opts[:update]
         when String, Symbol
-          -> { send(opts[:update]) }
+          ->(value) { send(opts[:update], value) }
         else
           ->(value) { update({ cache_name => value }) }
         end
@@ -105,14 +117,17 @@ module BipolarCache
         when Proc
           opts[:chance]
         when Integer, Float
+          raise ArgumentError, "chance must be >= 0, got #{opts[:chance]}" if opts[:chance].negative?
+          raise ArgumentError, "chance must be <= 100, got #{opts[:chance]}" if opts[:chance] > 100
+
           normalised_chance = if opts[:chance] > 1
-                                opts[:chance] / 100
+                                opts[:chance] / 100.0
                               else
                                 opts[:chance]
                               end
           ->(_value) { normalised_chance }
         else # default
-          ->(value) { value < 10 ? 0.1 : 0.9 }
+          ->(value) { (value || 0) < 10 ? 0.1 : 0.9 }
         end
       end
 
@@ -121,7 +136,7 @@ module BipolarCache
           opts[:rescue]
         else # default
           lambda { |e|
-            e.inspect
+            warn "[BipolarCache] #{e.class}: #{e.message}"
             0
           }
         end

data/lib/bipolar_cache/version.rb

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

data/lib/bipolar_cache.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 require_relative "bipolar_cache/version"
-require_relative "bipolar_cache/sequel/plugin_alpha"
 
 module BipolarCache
   class Error < StandardError; end
@@ -34,6 +33,8 @@ module BipolarCache
       actual_value
     end
   rescue StandardError => e
-    procs[:rescue].call(e) if procs[:rescue].is_a?(Proc)
+    raise unless procs[:rescue].is_a?(Proc)
+
+    procs[:rescue].call(e)
   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.4.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
@@ -29,9 +28,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 +44,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.8
 specification_version: 4
-summary: BipolarCache. Probabalistic caching toolkit.
+summary: BipolarCache. Probabilistic caching toolkit.
 test_files: []