type_balancer_rails 0.2.6 → 0.2.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3a0c6351fbf82429fbfeed86c19f07b576be7225d9e885256dcfab1022fb4868
-  data.tar.gz: 32f1b7feb2695fd2b390fa2cd36dd4e5bcbef29c9f9f9f7af4a609a441b2e7bc
+  metadata.gz: 9866aa8259f829d620cf73c8646ca94d0df346fb919f2b9c162541e0206e39d7
+  data.tar.gz: 1869524e7b9660adae5e6a86e8e6807306d61ad6927ad2192005b12236f2ef09
 SHA512:
-  metadata.gz: 3e7cfc07660ba22fe7f53db4a77be6d2e0216264644a9f796144efb0f49d88fe047d4ade15020c7f572308b8d561b8785c4c5c9ded470d26b294ae5b76316527
-  data.tar.gz: 6c43394a7cc216682ae10f98148b7df53e7d4a0acde867c82cc436bdb192bce214aa351e81bf09cd1c0a84faac27936f1ff66520e3ad89bab384afdc6a8676a6
+  metadata.gz: 98609db2225b4e762f7445bcc2fcf675e7995c49b1c41699ae5e5c2c706f34e0dbe88945b6bcf72f0651c2f92e2648c0515bda048df0631dd322e0abf3caaa5e
+  data.tar.gz: 2f8371a767e3301c57ffb3cf9bc16ae9e9e5e6ffe381ef97230632837eef7e9157f2968e40735fc00c8a2662e1f5dc56f5fb12644ed298b36a6162e0c5fe1d74

data/.rubocop.yml

@@ -41,6 +41,8 @@ Metrics/MethodLength:
 
 Metrics/AbcSize:
   Max: 20
+  Exclude:
+    - 'spec/**/*'
 
 Metrics/ClassLength:
   Max: 200

data/CHANGELOG.md

@@ -1,4 +1,38 @@
-## [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
+
+- Always-on pagination: Results from `balance_by_type` are now always paginated for performance (default: 20 per page, page 1). There is no option to disable pagination.
+- Added support for `per_page` and `page` options to control result size and page.
+- Added support for `expires_in` option to override the default cache expiration (default: 10 minutes) per call.
+- Cache adapter is now a first-class, configurable component (`TypeBalancer::Rails.cache_adapter`).
+- Improved documentation and architecture overview to reflect new pagination and caching behavior.
+- RuboCop and test stability improvements.
 
 ## [0.2.6] - 2025-05-01
 

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:
@@ -82,6 +114,82 @@ The `balance_by_type` method preserves the ActiveRecord query interface:
              .per(20)
 ```
 
+### Pagination and Caching (Always Enabled)
+
+Results from `balance_by_type` are **always paginated** for performance reasons. By default, only the first 20 balanced records are returned. You can control the page size and which page is returned using the `per_page` and `page` options:
+
+```ruby
+# Get the first 20 balanced records (default)
+@posts = Post.all.balance_by_type
+
+# Get the second page of 10 balanced records
+@posts = Post.all.balance_by_type(type_field: :category, per_page: 10, page: 2)
+```
+
+- **Default page size:** 20
+- **Default page:** 1
+- **Pagination is required:** There is no option to disable pagination. This is necessary for performance, especially on large datasets.
+
+#### Cache Expiration
+
+Balanced results are cached by default for 10 minutes to improve performance and reduce redundant calculations. You can override the cache expiration for a specific call by passing the `expires_in` option:
+
+```ruby
+# Cache the balanced results for 1 hour instead of 10 minutes
+@posts = Post.all.balance_by_type(type_field: :category, expires_in: 1.hour)
+```
+
+- **Default cache expiration:** 10 minutes
+- **Custom cache expiration:** Pass `expires_in: ...` (e.g., `expires_in: 1.hour`)
+
+> **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/benchmarks/collection_methods_benchmark.rb

@@ -0,0 +1,43 @@
+#!/usr/bin/env ruby
+# /Users/carl/gems/type_balancer-rails/benchmarks/collection_methods_benchmark.rb
+
+require 'bundler/setup'
+require 'type_balancer'
+require 'active_record'
+require 'benchmark'
+require_relative '../lib/type_balancer/rails'
+
+# Setup in-memory SQLite DB and model
+db_path = ':memory:'
+ActiveRecord::Base.establish_connection(adapter: 'sqlite3', database: db_path)
+
+# Define a simple model for benchmarking
+class Item < ActiveRecord::Base; end
+
+# Create table and seed data
+ActiveRecord::Schema.define do
+  create_table :items, force: true do |t|
+    t.string :media_type
+  end
+end
+
+# Seed with N records, distributed across types
+N = 20_000
+types = ['video', 'article', 'podcast']
+puts "Seeding #{N} records..."
+N.times do |i|
+  Item.create!(media_type: types[i % types.size])
+end
+puts 'Seeding complete.'
+
+# Extend the relation with CollectionMethods
+relation = Item.all.extending(TypeBalancer::Rails::CollectionMethods)
+
+# Benchmark balance_by_type
+puts "\nBenchmarking balance_by_type on #{N} records..."
+Benchmark.bm(20) do |x|
+  x.report('balance_by_type:') do
+    result = relation.balance_by_type(type_field: :media_type)
+    result.to_a
+  end
+end

data/docs/architecture_overview.md

@@ -0,0 +1,148 @@
+# TypeBalancer Rails Gem: Architecture Overview
+
+## 1. Project Summary
+
+TypeBalancer Rails is a Ruby gem designed to provide advanced balancing and ordering capabilities for ActiveRecord collections in Rails applications. Its primary feature is the ability to balance records by a specified type, ensuring even distribution and flexible pagination of heterogeneous data sets. The gem is intended for use in Rails projects that require sophisticated content or resource balancing, such as feeds, dashboards, or content aggregators.
+
+---
+
+## 2. Architecture & Dependencies
+
+### High-Level Architecture
+- **Core Module:** The gem's core logic is implemented under `lib/type_balancer/rails/`, with extensions for ActiveRecord and integration with Rails via a Railtie.
+- **ActiveRecord Integration:** The gem extends ActiveRecord models and relations to provide the `balance_by_type` method, which can be called on any model or relation.
+- **Rails Integration:** A Railtie ensures the gem is loaded and configured automatically in Rails environments.
+- **Generators:** The gem provides a Rails generator for easy installation and configuration.
+
+### Key Dependencies
+- **active_support**: Used for concerns, core extensions, and Rails integration.
+- **active_record**: The gem extends ActiveRecord models and relations.
+- **type_balancer**: The core balancing logic is delegated to the `type_balancer` gem (see below).
+- **Rails (optional)**: For automatic integration via Railtie and generator support.
+
+### About the TypeBalancer Gem
+
+TypeBalancer is a Ruby gem that provides advanced algorithms for distributing items of different types evenly across a sequence. Its primary use case is to ensure that, in collections where certain types (e.g., articles, images, videos) are overrepresented, the output is balanced so that all types are fairly and optimally spaced. This is especially useful for content feeds, e-commerce listings, news aggregators, and recommendation systems.
+
+**Key Features:**
+- Balances collections by type, ensuring optimal spacing and respecting type ratios.
+- Uses a sophisticated sliding window strategy by default, with support for custom window sizes and type orderings.
+- Extensible strategy system for future balancing algorithms.
+- Thread-safe, memory-efficient, and suitable for real-time processing of collections up to 10,000 items.
+- No external dependencies and high performance across Ruby versions.
+
+**Core API:**
+- `TypeBalancer.balance(items, type_field: :type, strategy: :sliding_window, window_size: 10, type_order: [...])`  
+  Balances an array of items by the specified type field, using the chosen strategy and options.
+- `TypeBalancer.calculate_positions(total_count:, ratio:, available_items: [...])`  
+  Calculates optimal positions for a given type or subset within a sequence.
+
+**Integration with Rails:**
+- The TypeBalancer Rails gem acts as a façade and adapter, exposing TypeBalancer's balancing logic as an easy-to-use method (`balance_by_type`) on ActiveRecord relations and models.
+- This allows Rails developers to leverage advanced balancing in queries and collections with minimal setup.
+
+---
+
+## 3. Class & Module Documentation
+
+### `TypeBalancer::Rails::CollectionMethods`
+- **Location:** `lib/type_balancer/rails/collection_methods.rb`
+- **Purpose:**
+  - Provides the `balance_by_type` method for ActiveRecord::Relation, enabling balanced selection and ordering of records by a type field.
+  - **Always paginates results** for performance. Default: 20 per page, page 1. There is no option to disable pagination.
+  - Supports `per_page` and `page` options to control result size and page.
+  - **Results are cached** for 10 minutes by default, but you can override this per call with the `expires_in` option (e.g., `expires_in: 1.hour`).
+  - Handles result ordering and cache key generation.
+- **Dependencies:**
+  - Depends on `TypeBalancer.balance` for core balancing logic.
+  - Expects to be included in ActiveRecord::Relation.
+- **Patterns:**
+  - Adapter/Extension pattern for ActiveRecord::Relation.
+
+### `TypeBalancer::Rails::ActiveRecordExtension`
+- **Location:** `/Users/carl/gems/type_balancer-rails/lib/type_balancer/rails/active_record_extension.rb`
+- **Purpose:**
+  - Provides a concern to extend ActiveRecord models with type balancing configuration and class-level `balance_by_type` method.
+  - Ensures `CollectionMethods` is included in ActiveRecord::Relation.
+- **Dependencies:**
+  - `ActiveSupport::Concern`, `ActiveRecord::Relation`, `TypeBalancer::Rails::CollectionMethods`.
+- **Patterns:**
+  - Rails Concern, Extension.
+
+### `TypeBalancer::Rails::Railtie`
+- **Location:** `/Users/carl/gems/type_balancer-rails/lib/type_balancer/rails/railtie.rb`
+- **Purpose:**
+  - Integrates the gem with Rails, ensuring the ActiveRecord extension is loaded automatically.
+- **Dependencies:**
+  - `Rails::Railtie`, `ActiveSupport.on_load(:active_record)`.
+- **Patterns:**
+  - Railtie for Rails integration.
+
+### `TypeBalancer::Rails::VERSION`
+- **Location:** `/Users/carl/gems/type_balancer-rails/lib/type_balancer/rails/version.rb`
+- **Purpose:**
+  - Defines the gem's version constant.
+- **Dependencies:** None.
+
+### `TypeBalancer::Rails` (Module)
+- **Location:** `/Users/carl/gems/type_balancer-rails/lib/type_balancer/rails.rb`
+- **Purpose:**
+  - Loads and wires up all Rails-specific extensions and dependencies for the gem.
+  - **Exposes a configurable cache adapter** (`TypeBalancer::Rails.cache_adapter`) used for caching balanced results.
+- **Dependencies:**
+  - `active_support`, `active_record`, `TypeBalancer::Rails::ActiveRecordExtension`, `TypeBalancer::Rails::CollectionMethods`.
+
+### Main Entry File
+- **Location:** `/Users/carl/gems/type_balancer-rails/lib/type_balancer_rails.rb`
+- **Purpose:**
+  - Loads all required dependencies and sets up the gem for use in a Rails environment.
+  - Loads the Railtie if Rails is present.
+
+### Generator: `TypeBalancer::Generators::InstallGenerator`
+- **Location:** `/Users/carl/gems/type_balancer-rails/lib/generators/type_balancer/install/install_generator.rb`
+- **Purpose:**
+  - Provides a Rails generator for installing TypeBalancer configuration into a Rails app.
+- **Dependencies:**
+  - Rails generator framework.
+- **Patterns:**
+  - Generator pattern for Rails setup.
+
+---
+
+## 4. Testing Strategy
+
+- **Unit Tests:**
+  - Located in `/Users/carl/gems/type_balancer-rails/spec/`.
+  - Organized by feature/module (e.g., `spec/type_balancer/rails/collection_methods_spec.rb`).
+  - Do **not** use a database; all database and dependency interactions are strictly mocked or stubbed.
+  - Shared contexts and helpers are provided in `spec/support/` (e.g., `test_helpers.rb`, `test_fixtures.rb`).
+  - Test models for mocking are in `spec/support/models/`.
+
+- **Integration Tests:**
+  - Located in the example Rails app under `/Users/carl/gems/type_balancer-rails/example/`.
+  - Example app contains its own `spec/` directory with feature, controller, and model specs.
+  - Integration tests use a real database and Rails stack to verify end-to-end behavior.
+  - Example app includes its own Gemfile and configuration for isolated testing.
+
+- **Testing Practices:**
+  - Unit tests focus on class responsibilities and use mocking for all external dependencies.
+  - Integration tests are only created in the example app and are not run as part of the main gem's unit test suite.
+  - No direct tests of private methods; only public interfaces are tested.
+  - RSpec is used as the test framework throughout.
+  - RuboCop is used for code style enforcement (`.rubocop.yml` present in both root and example app).
+  - CI and test runner setup is inferred from the presence of `.rspec`, `.rspec_status`, and Rakefile.
+
+- **Interesting/Unique Practices:**
+  - Strict separation of unit and integration tests, with clear boundaries and no database usage in unit tests.
+  - Use of shared contexts and helpers to DRY up test setup.
+  - Example app serves as a living integration testbed for real-world Rails usage.
+
+---
+
+## 5. Additional Notes
+- All file paths in this documentation are absolute, per project standards.
+- The gem follows SOLID principles and Rails best practices, with minimal monkey-patching and clear extension points.
+- **Pagination and caching are always enabled for performance reasons.**
+  - Default: 20 per page, page 1, 10 minute cache expiration.
+  - Use `per_page`, `page`, and `expires_in` options to customize.
+- For more details, see the README and inline code comments. 

data/example/Gemfile.lock

@@ -1,10 +1,10 @@
 PATH
   remote: ..
   specs:
-    type_balancer_rails (0.2.5)
+    type_balancer_rails (0.2.8)
       activerecord (>= 7.0, < 9.0)
       activesupport (>= 7.0, < 9.0)
-      type_balancer (~> 0.2.0)
+      type_balancer (>= 0.2.1)
 
 GEM
   remote: https://rubygems.org/
@@ -381,7 +381,7 @@ GEM
     turbo-rails (2.0.13)
       actionpack (>= 7.1.0)
       railties (>= 7.1.0)
-    type_balancer (0.2.0)
+    type_balancer (0.2.1)
     tzinfo (2.0.6)
       concurrent-ruby (~> 1.0)
     unicode-display_width (3.1.4)

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/features/contents_balancing_spec.rb

@@ -9,7 +9,7 @@ RSpec.feature 'Contents balancing', type: :feature do
     # Collect the categories from the second column of the table rows
     categories = page.all('table tbody tr').map { |row| row.all('td')[1]&.text }.compact
 
-    expect(categories.count).to eq(Content.count)
+    expect(categories.count).to eq(20)
     # There should be a mix of categories, not just a long run of one category
     expect(categories.uniq.sort).to eq(%w[blog news tutorial])
     # Check that the first 10 are not all the same (skewed fixture would be all news)

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

@@ -0,0 +1,38 @@
+module TypeBalancer
+  module Rails
+    class CacheAdapter
+      def initialize
+        @memory_cache = {}
+      end
+
+      def fetch(key, options = {}, &block)
+        if defined?(::Rails) && ::Rails.respond_to?(:cache) && ::Rails.cache
+          ::Rails.cache.fetch(key, options, &block)
+        else
+          @memory_cache[key] ||= block.call
+        end
+      end
+
+      def write(key, value, options = {})
+        if defined?(::Rails) && ::Rails.respond_to?(:cache) && ::Rails.cache
+          ::Rails.cache.write(key, value, options)
+        else
+          @memory_cache[key] = value
+        end
+      end
+
+      def delete(key)
+        if defined?(::Rails) && ::Rails.respond_to?(:cache) && ::Rails.cache
+          ::Rails.cache.delete(key)
+        else
+          @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

@@ -6,52 +6,60 @@ module TypeBalancer
     # Provides collection methods for balancing by type
     # These methods are extended onto ActiveRecord::Relation
     module CollectionMethods
-      def balance_by_type(options = {})
-        records = to_a
-        return empty_relation if records.empty?
-
-        type_field = fetch_type_field(options).to_sym
-        type_counts = records.group_by { |r| r.send(type_field).to_s }.transform_values(&:count)
-        type_order = compute_type_order(type_counts)
-        items = build_items(records, type_field)
+      require 'digest/md5'
 
-        balanced = TypeBalancer.balance(
-          items,
-          type_field: type_field,
-          type_order: type_order
-        )
-
-        return empty_relation if balanced.nil?
-
-        paged = apply_pagination(balanced, options)
+      def balance_by_type(options = {})
+        type_field, offset, per_page = pagination_params(options)
+        cache_key = build_cache_key(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?
 
-        build_result(paged)
+        order_by_ids(page_ids)
       end
 
       private
 
-      def apply_pagination(records, options)
-        return records unless options[:page] || options[:per_page]
+      def pagination_params(options)
+        type_field = fetch_type_field(options).to_sym
+        page      = (options[:page] || 1).to_i
+        per_page  = (options[:per_page] || 20).to_i
+        offset    = (page - 1) * per_page
+        [type_field, offset, per_page]
+      end
 
-        page     = (options[:page] || 1).to_i
-        per_page = (options[:per_page] || 20).to_i
-        offset   = (page - 1) * per_page
-        records[offset, per_page] || []
+      def build_cache_key(type_field)
+        [
+          'type_balancer',
+          klass.name,
+          type_field,
+          Digest::MD5.hexdigest(to_sql)
+        ].join(':')
       end
 
-      def build_result(balanced)
-        flattened = balanced.flatten(1)
-        ids = flattened.map { |h| h[:id] }
-        unless klass.respond_to?(:where)
-          raise TypeError, 'balance_by_type can only be called on an ActiveRecord::Relation or compatible object'
-        end
+      def compute_ids(type_field)
+        records     = select(:id, type_field)
+        items       = records.map { |r| { id: r.id, type_field => r.public_send(type_field) } }
+        type_counts = items.group_by { |h| h[type_field] }.transform_values(&:size)
+        order       = compute_type_order(type_counts)
+        balanced    = TypeBalancer.balance(items, type_field: type_field, type_order: order)
+        balanced ? balanced.flatten(1).map { |h| h[:id] } : []
+      rescue TypeBalancer::EmptyCollectionError
+        []
+      end
 
-        relation = klass.where(id: ids)
-        if ids.any?
-          case_sql = "CASE id #{ids.each_with_index.map { |id, idx| "WHEN #{id} THEN #{idx}" }.join(' ')} END"
-          relation = relation.order(Arel.sql(case_sql))
-        end
-        relation
+      def order_by_ids(ids)
+        case_sql = "CASE id #{ids.each_with_index.map { |id, idx| "WHEN #{id} THEN #{idx}" }.join(' ')} END"
+        klass.where(id: ids).order(Arel.sql(case_sql))
       end
 
       def empty_relation
@@ -70,28 +78,6 @@ module TypeBalancer
       def compute_type_order(type_counts)
         type_counts.sort_by { |_, count| count }.map(&:first)
       end
-
-      def build_items(records, type_field)
-        records.map do |record|
-          { id: record.id, type_field => record.send(type_field).to_s }
-        end
-      end
-
-      def logger?
-        defined?(::Rails) && ::Rails.logger
-      end
-
-      def balance_results_lines(balanced, _type_field)
-        if balanced.nil?
-          ['Balanced result is nil!']
-        else
-          [
-            "First 10 balanced types: \#{balanced.first(10).map { |h| h[type_field] }.inspect}",
-            "Unique types in first 10: \#{balanced.first(10).map { |h| h[type_field] }.uniq.inspect}",
-            "Total balanced items: \#{balanced.size}"
-          ]
-        end
-      end
     end
   end
 end

data/lib/type_balancer/rails/version.rb

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

data/lib/type_balancer/rails.rb

@@ -6,8 +6,23 @@ require 'active_record'
 
 require_relative 'rails/active_record_extension'
 require_relative 'rails/collection_methods'
+require_relative 'rails/cache_adapter'
 
 module TypeBalancer
   module Rails
+    class << self
+      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.6
+  version: 0.2.8
 platform: ruby
 authors:
 - Carl Smith
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-05-01 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
@@ -78,6 +78,8 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
+- benchmarks/collection_methods_benchmark.rb
+- docs/architecture_overview.md
 - example/.dockerignore
 - example/.rspec
 - example/.rubocop.yml
@@ -145,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
@@ -164,6 +167,7 @@ files:
 - lib/generators/type_balancer/install/templates/type_balancer.rb.erb
 - lib/type_balancer/rails.rb
 - lib/type_balancer/rails/active_record_extension.rb
+- lib/type_balancer/rails/cache_adapter.rb
 - lib/type_balancer/rails/collection_methods.rb
 - lib/type_balancer/rails/railtie.rb
 - lib/type_balancer/rails/version.rb