type_balancer_rails 0.2.7 → 0.2.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3d4ba73db98a7266039db3cf00de37983a4348514d93f7ae1420f4d87be88144
-  data.tar.gz: 54a10ed555eaaae52dc37b3ca0e8ed86a6f5d61d155333e08ad4fad9da2baa58
+  metadata.gz: 9866aa8259f829d620cf73c8646ca94d0df346fb919f2b9c162541e0206e39d7
+  data.tar.gz: 1869524e7b9660adae5e6a86e8e6807306d61ad6927ad2192005b12236f2ef09
 SHA512:
-  metadata.gz: f289f1d2feadaf05fd1b1e2d4e5b51cd1fa1a6809ccce0fa5ff27347c0c652dc20523ff776339ec2e9a7c5ec3a8f67da9f97d0a1a2ed53287220da3206ed6ec8
-  data.tar.gz: c18b3c8cc22192f5df37c61e3633406c75718e9c2e27a1d34a16838198b4bcf8b95a267e104e9dbb849c3a0d7991f607d9110a4a18146ec6a6b54faa7fb653ae
+  metadata.gz: 98609db2225b4e762f7445bcc2fcf675e7995c49b1c41699ae5e5c2c706f34e0dbe88945b6bcf72f0651c2f92e2648c0515bda048df0631dd322e0abf3caaa5e
+  data.tar.gz: 2f8371a767e3301c57ffb3cf9bc16ae9e9e5e6ffe381ef97230632837eef7e9157f2968e40735fc00c8a2662e1f5dc56f5fb12644ed298b36a6162e0c5fe1d74

data/CHANGELOG.md

@@ -1,4 +1,29 @@
-## [Unreleased]
+## [0.2.8] - 2025-05-10
+
+- **Rails-style configuration block:**
+  You can now configure TypeBalancer Rails in an initializer using:
+  ```ruby
+  TypeBalancer::Rails.configure do |config|
+    config.cache_adapter = TypeBalancer::Rails::CacheAdapter.new
+    config.cache_expiry_seconds = 600
+  end
+  ```
+  Direct assignment is still supported for backward compatibility.
+
+- **Per-request cache control:**
+  `balance_by_type` now accepts:
+  - `expires_in:` (override cache expiry for a single call)
+  - `cache_reset:` (force cache refresh for a single call)
+
+- **Global cache expiry configuration:**
+  Set the default cache expiry for all balanced queries via `TypeBalancer::Rails.cache_expiry_seconds`.
+
+- **Cache clearing:**
+  Use `TypeBalancer::Rails.clear_cache!` to clear all cached balanced results (e.g., from a console or admin task).
+
+### Changed
+- **Caching and pagination are always enabled** for performance and reliability.
+- **Cache keys are now isolated** per model and type field, preventing cross-contamination.
 
 ## [0.2.7] - 2025-05-04
 

data/README.md

@@ -26,6 +26,38 @@ Or install it yourself as:
 $ gem install type_balancer_rails
 ```
 
+## Caching and Performance
+
+Type balancing can be computationally expensive, especially on large datasets. To ensure efficient performance, **TypeBalancer Rails automatically caches the balanced ID list for each query**. This means:
+- The balancing algorithm only runs when needed (on cache miss or reset).
+- Subsequent requests for the same query use the cached result, reducing database and CPU load.
+- Caching is essential for production use. Disabling or misconfiguring cache may result in slow queries.
+
+**Adjust cache settings thoughtfully:**
+- Shorter expiries mean fresher data but more frequent recalculation.
+- Longer expiries improve performance but may serve stale results if your data changes often.
+
+## Configuration
+
+To customize caching and performance, use the Rails-style configuration block in an initializer (e.g., `config/initializers/type_balancer.rb`):
+
+```ruby
+TypeBalancer::Rails.configure do |config|
+  # Use the default cache adapter (backed by Rails.cache)
+  config.cache_adapter = TypeBalancer::Rails::CacheAdapter.new
+
+  # Set the global cache expiry (in seconds)
+  # Default is 600 (10 minutes). Adjust as needed for your app's freshness/performance needs.
+  config.cache_expiry_seconds = 600
+end
+```
+
+> **Note:** You can also set these options directly
+> ```ruby
+> TypeBalancer::Rails.cache_adapter = TypeBalancer::Rails::CacheAdapter.new
+> TypeBalancer::Rails.cache_expiry_seconds = 600
+> ```
+
 ## Usage
 
 To balance records by a given type field, use the following syntax:
@@ -112,6 +144,52 @@ Balanced results are cached by default for 10 minutes to improve performance and
 
 > **Note:** If you need to retrieve all balanced records, you must manually iterate through all pages.
 
+### Per-request Cache Control
+
+You can override cache behavior for a single call to `balance_by_type`:
+
+- **Custom Expiry:**
+  ```ruby
+  # Cache the balanced results for 1 hour for this request only
+  @posts = Post.all.balance_by_type(type_field: :category, expires_in: 1.hour)
+  ```
+- **Force Cache Reset:**
+  ```ruby
+  # Force recalculation and cache update for this request
+  @posts = Post.all.balance_by_type(type_field: :category, cache_reset: true)
+  ```
+
+#### Controller Example
+
+You can pass these options from controller params:
+
+```ruby
+class PostsController < ApplicationController
+  def index
+    @posts = Post.all.balance_by_type(
+      type_field: params[:type_field],
+      expires_in: params[:expires_in],
+      cache_reset: params[:cache_reset].present?
+    )
+  end
+end
+```
+
+## Cache Management and Isolation
+
+- **Cache keys are unique per model and type field.**
+- There is no cross-contamination between different models or type fields.
+- If you use multiple type fields or models, each will have its own cache entry.
+- To avoid stale data, clear the cache after bulk updates or schema changes using `TypeBalancer::Rails.clear_cache!`.
+
+## Upgrade Notes
+
+- `balance_by_type` now supports per-request `expires_in` and `cache_reset` options.
+- Global cache expiry is configurable via `TypeBalancer::Rails.cache_expiry_seconds`.
+- You can clear all cached results with `TypeBalancer::Rails.clear_cache!`.
+- Caching is always enabled and required for performance.
+- Pagination is always enabled; you must page through results if you want all records.
+
 ## Planned Enhancements
 
 - Support for passing a symbol directly to `balance_by_type`, e.g., `balance_by_type(:media_type)`, for more ergonomic usage. This is planned for a future version.

data/example/Gemfile.lock

@@ -1,10 +1,10 @@
 PATH
   remote: ..
   specs:
-    type_balancer_rails (0.2.7)
+    type_balancer_rails (0.2.8)
       activerecord (>= 7.0, < 9.0)
       activesupport (>= 7.0, < 9.0)
-      type_balancer (~> 0.2.1)
+      type_balancer (>= 0.2.1)
 
 GEM
   remote: https://rubygems.org/

data/example/config/environments/test.rb

@@ -20,7 +20,7 @@ Rails.application.configure do
 
   # Show full error reports.
   config.consider_all_requests_local = true
-  config.cache_store = :null_store
+  config.cache_store = :memory_store
 
   # Render exception templates for rescuable exceptions and raise for other exceptions.
   config.action_dispatch.show_exceptions = :rescuable

data/example/spec/controllers/posts_controller_caching_spec.rb

@@ -0,0 +1,65 @@
+require 'rails_helper'
+
+RSpec.describe PostsController, type: :controller do
+  fixtures :posts
+
+  before do
+    Rails.cache.clear
+    allow(TypeBalancer).to receive(:balance).and_call_original
+  end
+
+  describe 'GET #index' do
+    it 'caches the balanced ID list and reuses it' do
+      # First call: should invoke the balancer
+      get :index
+      expect(TypeBalancer).to have_received(:balance).once
+      first_result = assigns(:posts).map(&:id)
+
+      # Second call: should use the cache, not call balancer again
+      get :index
+      expect(TypeBalancer).to have_received(:balance).once
+      second_result = assigns(:posts).map(&:id)
+      expect(second_result).to eq(first_result)
+    end
+
+    it 'resets the cache when requested via controller param' do
+      # Prime the cache
+      get :index
+      expect(TypeBalancer).to have_received(:balance).once
+      first_result = assigns(:posts).map(&:id)
+
+      # Simulate cache reset by passing param (assuming controller supports it)
+      allow(TypeBalancer).to receive(:balance).and_call_original # reset spy
+      get :index, params: { cache_reset: true }
+      expect(TypeBalancer).to have_received(:balance).once
+      second_result = assigns(:posts).map(&:id)
+      expect(second_result).to eq(first_result) # Should still be balanced, but balancer called again
+    end
+
+    it 'isolates cache by type field' do
+      get :index, params: { type_field: 'media_type' }
+      expect(TypeBalancer).to have_received(:balance).once
+      allow(TypeBalancer).to receive(:balance).and_call_original # reset spy
+      get :index, params: { type_field: 'other_type' }
+      expect(TypeBalancer).to have_received(:balance).once
+    end
+
+    it 'respects per-request expires_in option' do
+      get :index, params: { expires_in: 1 }
+      expect(TypeBalancer).to have_received(:balance).once
+      sleep 2
+      allow(TypeBalancer).to receive(:balance).and_call_original # reset spy
+      get :index, params: { expires_in: 1 }
+      expect(TypeBalancer).to have_received(:balance).once
+    end
+
+    it 'expires cache and calls balancer again after expiry' do
+      get :index, params: { expires_in: 1 }
+      expect(TypeBalancer).to have_received(:balance).once
+      sleep 2
+      allow(TypeBalancer).to receive(:balance).and_call_original # reset spy
+      get :index, params: { expires_in: 1 }
+      expect(TypeBalancer).to have_received(:balance).once
+    end
+  end
+end

data/example/spec/models/content_spec.rb

@@ -19,6 +19,7 @@ RSpec.describe Content, type: :model do
 
   describe 'type balancing with real records' do
     before do
+      TypeBalancer::Rails.clear_cache!
       described_class.delete_all
       @content1 = described_class.create!(title: 'Content 1', content_type: 'blog')
       @content2 = described_class.create!(title: 'Content 2', content_type: 'news')

data/example/spec/models/post_spec.rb

@@ -16,6 +16,7 @@ RSpec.describe Post, type: :model do
     let(:another_video_post) { described_class.create!(title: 'Post 3', media_type: 'video') }
 
     before do
+      TypeBalancer::Rails.clear_cache!
       described_class.delete_all
       video_post; article_post; another_video_post  # Create the records
     end

data/lib/type_balancer/rails/cache_adapter.rb

@@ -28,6 +28,11 @@ module TypeBalancer
           @memory_cache.delete(key)
         end
       end
+
+      def clear_cache!
+        ::Rails.cache.clear if defined?(::Rails) && ::Rails.respond_to?(:cache) && ::Rails.cache
+        @memory_cache.clear
+      end
     end
   end
 end

data/lib/type_balancer/rails/collection_methods.rb

@@ -11,8 +11,15 @@ module TypeBalancer
       def balance_by_type(options = {})
         type_field, offset, per_page = pagination_params(options)
         cache_key = build_cache_key(type_field)
-        ids = TypeBalancer::Rails.cache_adapter.fetch(cache_key, expires_in: 10.minutes) do
-          compute_ids(type_field)
+        expires_in = options[:expires_in] || ::TypeBalancer::Rails.cache_expiry_seconds
+        cache_reset = options[:cache_reset]
+        if cache_reset
+          ids = compute_ids(type_field)
+          TypeBalancer::Rails.cache_adapter.write(cache_key, ids, expires_in: expires_in)
+        else
+          ids = TypeBalancer::Rails.cache_adapter.fetch(cache_key, expires_in: expires_in) do
+            compute_ids(type_field)
+          end
         end
         page_ids = ids[offset, per_page] || []
         return empty_relation if page_ids.empty?

data/lib/type_balancer/rails/version.rb

@@ -2,6 +2,6 @@
 
 module TypeBalancer
   module Rails
-    VERSION = '0.2.7'
+    VERSION = '0.2.8'
   end
 end

data/lib/type_balancer/rails.rb

@@ -11,8 +11,18 @@ require_relative 'rails/cache_adapter'
 module TypeBalancer
   module Rails
     class << self
-      attr_accessor :cache_adapter
+      attr_accessor :cache_adapter, :cache_expiry_seconds
+
+      def clear_cache!
+        cache_adapter&.clear_cache!
+      end
+
+      # Rails-style configuration block
+      def configure
+        yield self if block_given?
+      end
     end
     self.cache_adapter ||= TypeBalancer::Rails::CacheAdapter.new
+    self.cache_expiry_seconds ||= 600 # 10 minutes default
   end
 end

data/type_balancer_rails.gemspec

@@ -32,7 +32,7 @@ Gem::Specification.new do |spec|
   # Runtime dependencies
   spec.add_dependency 'activerecord', '>= 7.0', '< 9.0'
   spec.add_dependency 'activesupport', '>= 7.0', '< 9.0'
-  spec.add_dependency 'type_balancer', '~> 0.2.1'
+  spec.add_dependency 'type_balancer', '>= 0.2.1'
 
   # For more information and examples about making a new gem, check out our
   # guide at: https://bundler.io/guides/creating_gem.html

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: type_balancer_rails
 version: !ruby/object:Gem::Version
-  version: 0.2.7
+  version: 0.2.8
 platform: ruby
 authors:
 - Carl Smith
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-05-05 00:00:00.000000000 Z
+date: 2025-05-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -54,14 +54,14 @@ dependencies:
   name: type_balancer
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: 0.2.1
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: 0.2.1
 description: Provides Rails integration for the type_balancer gem
@@ -147,6 +147,7 @@ files:
 - example/lib/tasks/dev_fixtures.rake
 - example/script/.keep
 - example/spec/controllers/contents_controller_spec.rb
+- example/spec/controllers/posts_controller_caching_spec.rb
 - example/spec/controllers/posts_controller_spec.rb
 - example/spec/features/contents_balancing_spec.rb
 - example/spec/features/posts_balancing_spec.rb