type_balancer_rails 0.2.0 → 0.2.3

data/example/db/migrate/20250427174733_create_posts.rb

@@ -0,0 +1,10 @@
+class CreatePosts < ActiveRecord::Migration[8.0]
+  def change
+    create_table :posts do |t|
+      t.string :title
+      t.string :media_type
+
+      t.timestamps
+    end
+  end
+end

data/example/db/migrate/20250427174747_create_contents.rb

@@ -0,0 +1,11 @@
+class CreateContents < ActiveRecord::Migration[8.0]
+  def change
+    create_table :contents do |t|
+      t.string :title
+      t.string :category
+      t.string :content_type
+
+      t.timestamps
+    end
+  end
+end

data/example/db/schema.rb

@@ -0,0 +1,28 @@
+# This file is auto-generated from the current state of the database. Instead
+# of editing this file, please use the migrations feature of Active Record to
+# incrementally modify your database, and then regenerate this schema definition.
+#
+# This file is the source Rails uses to define your schema when running `bin/rails
+# db:schema:load`. When creating a new database, `bin/rails db:schema:load` tends to
+# be faster and is potentially less error prone than running all of your
+# migrations from scratch. Old migrations may fail to apply correctly if those
+# migrations use external dependencies or application code.
+#
+# It's strongly recommended that you check this file into your version control system.
+
+ActiveRecord::Schema[8.0].define(version: 2025_04_27_174747) do
+  create_table "contents", force: :cascade do |t|
+    t.string "title"
+    t.string "category"
+    t.string "content_type"
+    t.datetime "created_at", null: false
+    t.datetime "updated_at", null: false
+  end
+
+  create_table "posts", force: :cascade do |t|
+    t.string "title"
+    t.string "media_type"
+    t.datetime "created_at", null: false
+    t.datetime "updated_at", null: false
+  end
+end

data/example/db/seeds.rb

@@ -0,0 +1,9 @@
+# This file should ensure the existence of records required to run the application in every environment (production,
+# development, test). The code here should be idempotent so that it can be executed at any point in every environment.
+# The data can then be loaded with the bin/rails db:seed command (or created alongside the database with db:setup).
+#
+# Example:
+#
+#   ["Action", "Comedy", "Drama", "Horror"].each do |genre_name|
+#     MovieGenre.find_or_create_by!(name: genre_name)
+#   end

data/example/lib/tasks/dev_fixtures.rake

@@ -0,0 +1,12 @@
+namespace :dev do
+  desc "Load test fixtures into the development database (WARNING: this will delete all existing records in posts and contents!)"
+  task load_fixtures: :environment do
+    require "active_record/fixtures"
+    puts "Deleting all Posts and Contents..."
+    Post.delete_all
+    Content.delete_all
+    puts "Loading fixtures from test/fixtures..."
+    ActiveRecord::FixtureSet.create_fixtures("test/fixtures", [ "posts", "contents" ])
+    puts "Fixtures loaded!"
+  end
+end

data/example/spec/controllers/contents_controller_spec.rb

@@ -0,0 +1,27 @@
+require 'rails_helper'
+
+RSpec.describe ContentsController, type: :controller do
+  fixtures :contents
+
+  describe 'GET #balance_by_category' do
+    it 'assigns a balanced set of contents by category to @contents' do
+      get :balance_by_category
+      expect(assigns(:contents)).to be_present
+      original = Content.order(:id).pluck(:category)
+      balanced = assigns(:contents).pluck(:category)
+      expect(balanced).not_to eq(original)
+      expect(balanced.uniq.sort).to contain_exactly('blog', 'news', 'tutorial')
+    end
+  end
+
+  describe 'GET #balance_by_content_type' do
+    it 'assigns a balanced set of contents by content_type to @contents' do
+      get :balance_by_content_type
+      expect(assigns(:contents)).to be_present
+      original = Content.order(:id).pluck(:content_type)
+      balanced = assigns(:contents).pluck(:content_type)
+      expect(balanced).not_to eq(original)
+      expect(balanced.uniq.sort).to contain_exactly('article', 'image', 'video')
+    end
+  end
+end

data/example/spec/controllers/posts_controller_spec.rb

@@ -0,0 +1,16 @@
+require 'rails_helper'
+
+RSpec.describe PostsController, type: :controller do
+  fixtures :posts
+
+  describe 'GET #index' do
+    it 'assigns a balanced set of posts to @posts' do
+      get :index
+      expect(assigns(:posts)).to be_present
+      original = Post.order(:id).pluck(:media_type)
+      balanced = assigns(:posts).pluck(:media_type)
+      expect(balanced).not_to eq(original)
+      expect(balanced.uniq.sort).to contain_exactly('article', 'image', 'video')
+    end
+  end
+end

data/example/spec/features/contents_balancing_spec.rb

@@ -0,0 +1,18 @@
+require 'rails_helper'
+
+RSpec.feature 'Contents balancing', type: :feature do
+  fixtures :contents
+
+  scenario 'visiting the contents balance by category page displays contents balanced by category' do
+    visit '/contents/balance_by_category'
+    expect(page).to have_content('Contents (Balanced by :category)')
+    # 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)
+    # 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)
+    expect(categories.first(10).uniq.size).to be > 1
+  end
+end

data/example/spec/features/posts_balancing_spec.rb

@@ -0,0 +1,16 @@
+require 'rails_helper'
+
+RSpec.feature 'Posts balancing', type: :feature do
+  fixtures :posts
+
+  scenario 'visiting the posts index displays posts balanced by media_type' do
+    visit '/posts'
+    expect(page).to have_content('Posts (Balanced by :media_type)')
+    # Collect the media types from the second column of the table rows
+    media_types = page.all('table tbody tr').map { |row| row.all('td')[1]&.text }.compact
+    # There should be a mix of media types, not just a long run of one type
+    expect(media_types.uniq.sort).to eq(%w[article image video])
+    # Check that the first 10 are not all the same (skewed fixture would be all video)
+    expect(media_types.first(10).uniq.size).to be > 1
+  end
+end

data/example/spec/models/content_spec.rb

@@ -0,0 +1,19 @@
+require 'rails_helper'
+
+RSpec.describe Content, type: :model do
+  fixtures :contents
+
+  it 'balances contents by category' do
+    original = described_class.order(:id).pluck(:category)
+    balanced = described_class.all.balance_by_type(type_field: :category).pluck(:category)
+    expect(balanced).not_to eq(original)
+    expect(balanced.uniq.sort).to contain_exactly('blog', 'news', 'tutorial')
+  end
+
+  it 'balances contents by content_type' do
+    original = described_class.order(:id).pluck(:content_type)
+    balanced = described_class.all.balance_by_type(type_field: :content_type).pluck(:content_type)
+    expect(balanced).not_to eq(original)
+    expect(balanced.uniq.sort).to contain_exactly('article', 'image', 'video')
+  end
+end

data/example/spec/models/post_spec.rb

@@ -0,0 +1,12 @@
+require 'rails_helper'
+
+RSpec.describe Post, type: :model do
+  fixtures :posts
+
+  it 'balances posts by media_type' do
+    original = described_class.order(:id).pluck(:media_type)
+    balanced = described_class.all.balance_by_type(type_field: :media_type).pluck(:media_type)
+    expect(balanced).not_to eq(original)
+    expect(balanced.uniq.sort).to contain_exactly('article', 'image', 'video')
+  end
+end

data/example/spec/rails_helper.rb

@@ -0,0 +1,35 @@
+# This file is copied to spec/ when you run 'rails generate rspec:install'
+require 'spec_helper'
+ENV['RAILS_ENV'] ||= 'test'
+require_relative '../config/environment'
+# Prevent database truncation if the environment is production
+abort("The Rails environment is running in production mode!") if Rails.env.production?
+require 'rspec/rails'
+require 'capybara/rails'
+
+# Requires supporting ruby files with custom matchers and macros, etc, in
+# spec/support/ and its subdirectories.
+# Rails.root.glob('spec/support/**/*.rb').sort_by(&:to_s).each { |f| require f }
+
+# Checks for pending migrations and applies them before tests are run.
+# If you are not using ActiveRecord, you can remove these lines.
+begin
+  ActiveRecord::Migration.maintain_test_schema!
+rescue ActiveRecord::PendingMigrationError => e
+  abort e.to_s.strip
+end
+
+RSpec.configure do |config|
+  # Use test/fixtures for Rails-style fixtures
+  config.fixture_paths = [ "#{::Rails.root}/test/fixtures" ]
+  config.use_transactional_fixtures = true
+  config.include ActiveRecord::TestFixtures
+
+  # You can uncomment this line to turn off ActiveRecord support entirely.
+  # config.use_active_record = false
+
+  # Filter lines from Rails gems in backtraces.
+  config.filter_rails_from_backtrace!
+  # arbitrary gems may also be filtered via:
+  # config.filter_gems_from_backtrace("gem name")
+end

data/example/spec/spec_helper.rb

@@ -0,0 +1,94 @@
+# This file was generated by the `rails generate rspec:install` command. Conventionally, all
+# specs live under a `spec` directory, which RSpec adds to the `$LOAD_PATH`.
+# The generated `.rspec` file contains `--require spec_helper` which will cause
+# this file to always be loaded, without a need to explicitly require it in any
+# files.
+#
+# Given that it is always loaded, you are encouraged to keep this file as
+# light-weight as possible. Requiring heavyweight dependencies from this file
+# will add to the boot time of your test suite on EVERY test run, even for an
+# individual file that may not need all of that loaded. Instead, consider making
+# a separate helper file that requires the additional dependencies and performs
+# the additional setup, and require it from the spec files that actually need
+# it.
+#
+# See https://rubydoc.info/gems/rspec-core/RSpec/Core/Configuration
+RSpec.configure do |config|
+  # rspec-expectations config goes here. You can use an alternate
+  # assertion/expectation library such as wrong or the stdlib/minitest
+  # assertions if you prefer.
+  config.expect_with :rspec do |expectations|
+    # This option will default to `true` in RSpec 4. It makes the `description`
+    # and `failure_message` of custom matchers include text for helper methods
+    # defined using `chain`, e.g.:
+    #     be_bigger_than(2).and_smaller_than(4).description
+    #     # => "be bigger than 2 and smaller than 4"
+    # ...rather than:
+    #     # => "be bigger than 2"
+    expectations.include_chain_clauses_in_custom_matcher_descriptions = true
+  end
+
+  # rspec-mocks config goes here. You can use an alternate test double
+  # library (such as bogus or mocha) by changing the `mock_with` option here.
+  config.mock_with :rspec do |mocks|
+    # Prevents you from mocking or stubbing a method that does not exist on
+    # a real object. This is generally recommended, and will default to
+    # `true` in RSpec 4.
+    mocks.verify_partial_doubles = true
+  end
+
+  # This option will default to `:apply_to_host_groups` in RSpec 4 (and will
+  # have no way to turn it off -- the option exists only for backwards
+  # compatibility in RSpec 3). It causes shared context metadata to be
+  # inherited by the metadata hash of host groups and examples, rather than
+  # triggering implicit auto-inclusion in groups with matching metadata.
+  config.shared_context_metadata_behavior = :apply_to_host_groups
+
+# The settings below are suggested to provide a good initial experience
+# with RSpec, but feel free to customize to your heart's content.
+=begin
+  # This allows you to limit a spec run to individual examples or groups
+  # you care about by tagging them with `:focus` metadata. When nothing
+  # is tagged with `:focus`, all examples get run. RSpec also provides
+  # aliases for `it`, `describe`, and `context` that include `:focus`
+  # metadata: `fit`, `fdescribe` and `fcontext`, respectively.
+  config.filter_run_when_matching :focus
+
+  # Allows RSpec to persist some state between runs in order to support
+  # the `--only-failures` and `--next-failure` CLI options. We recommend
+  # you configure your source control system to ignore this file.
+  config.example_status_persistence_file_path = "spec/examples.txt"
+
+  # Limits the available syntax to the non-monkey patched syntax that is
+  # recommended. For more details, see:
+  # https://rspec.info/features/3-12/rspec-core/configuration/zero-monkey-patching-mode/
+  config.disable_monkey_patching!
+
+  # Many RSpec users commonly either run the entire suite or an individual
+  # file, and it's useful to allow more verbose output when running an
+  # individual spec file.
+  if config.files_to_run.one?
+    # Use the documentation formatter for detailed output,
+    # unless a formatter has already been configured
+    # (e.g. via a command-line flag).
+    config.default_formatter = "doc"
+  end
+
+  # Print the 10 slowest examples and example groups at the
+  # end of the spec run, to help surface which specs are running
+  # particularly slow.
+  config.profile_examples = 10
+
+  # Run specs in random order to surface order dependencies. If you find an
+  # order dependency and want to debug it, you can fix the order by providing
+  # the seed, which is printed after each run.
+  #     --seed 1234
+  config.order = :random
+
+  # Seed global randomization in this process using the `--seed` CLI option.
+  # Setting this allows you to use `--seed` to deterministically reproduce
+  # test failures related to randomization by passing the same `--seed` value
+  # as the one that triggered the failure.
+  Kernel.srand config.seed
+=end
+end

data/example/test/fixtures/contents.yml

@@ -0,0 +1,19 @@
+# Skewed distribution for demoing balancing on two fields
+<% 1.upto(30) do |i| %>
+news_video_<%= i %>:
+  title: "News Video <%= i %>"
+  category: news
+  content_type: video
+<% end %>
+<% 1.upto(15) do |i| %>
+blog_article_<%= i %>:
+  title: "Blog Article <%= i %>"
+  category: blog
+  content_type: article
+<% end %>
+<% 1.upto(5) do |i| %>
+tutorial_image_<%= i %>:
+  title: "Tutorial Image <%= i %>"
+  category: tutorial
+  content_type: image
+<% end %> 

data/example/test/fixtures/posts.yml

@@ -0,0 +1,16 @@
+# Skewed distribution for demoing balancing
+<% 1.upto(35) do |i| %>
+video_post_<%= i %>:
+  title: "Video Post <%= i %>"
+  media_type: "video"
+<% end %>
+<% 1.upto(10) do |i| %>
+article_post_<%= i %>:
+  title: "Article Post <%= i %>"
+  media_type: "article"
+<% end %>
+<% 1.upto(5) do |i| %>
+image_post_<%= i %>:
+  title: "Image Post <%= i %>"
+  media_type: "image"
+<% end %> 

data/lib/type_balancer/rails/collection_methods.rb

@@ -1,37 +1,30 @@
 # frozen_string_literal: true
 
+# lib/type_balancer/rails/collection_methods.rb
 module TypeBalancer
   module Rails
     # Provides collection methods for balancing by type
     # These methods are extended onto ActiveRecord::Relation
     module CollectionMethods
-      # Public: Balance the collection by type
-      #
-      # options - Hash of options to merge with model's type_balancer_options (default: {})
-      #          :type_field - Field to balance by (default: :type)
-      #          :page      - Page number for pagination (default: 1)
-      #          :per_page  - Number of items per page (default: 20)
-      #
-      # Examples
-      #
-      #   Post.all.balance_by_type
-      #   Post.where(published: true).balance_by_type(type_field: :category)
-      #   Post.all.balance_by_type(page: 2, per_page: 20)
-      #
-      # Returns ActiveRecord::Relation with balanced ordering
       def balance_by_type(options = {})
         records = to_a
         return empty_relation if records.empty?
 
-        type_field = fetch_type_field(options)
-        # Map to array of hashes with only id and type
-        id_and_type_hashes = records.map do |record|
-          { id: record.id, type: record.send(type_field) }
-        end
-        balanced = TypeBalancer.balance(id_and_type_hashes, type_field: :type)
+        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)
+
+        balanced = TypeBalancer.balance(
+          items,
+          type_field: type_field,
+          type_order: type_order
+        )
+
         return empty_relation if balanced.nil?
 
         paged = apply_pagination(balanced, options)
+
         build_result(paged)
       end
 
@@ -40,33 +33,65 @@ module TypeBalancer
       def apply_pagination(records, options)
         return records unless options[:page] || options[:per_page]
 
-        page      = (options[:page] || 1).to_i
-        per_page  = (options[:per_page] || 20).to_i
-        offset    = (page - 1) * per_page
+        page     = (options[:page] || 1).to_i
+        per_page = (options[:per_page] || 20).to_i
+        offset   = (page - 1) * per_page
         records[offset, per_page] || []
       end
 
       def build_result(balanced)
-        # Flatten in case balanced is a nested array
-        ids = balanced.flatten.map { |h| h[:id] }
-        # Map back to original records (works for both AR and TestRelation)
-        records_by_id = to_a.index_by(&:id)
-        ordered = ids.map { |id| records_by_id[id] }
-        self.class.new(ordered)
+        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
+
+        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
       end
 
       def empty_relation
-        if klass.respond_to?(:none)
-          klass.none
-        else
-          []
+        unless klass.respond_to?(:none)
+          raise TypeError, 'balance_by_type can only be called on an ActiveRecord::Relation or compatible object'
         end
+
+        klass.none
       end
 
       def fetch_type_field(options)
         model_opts = klass.respond_to?(:type_balancer_options) ? klass.type_balancer_options : {}
         options[:type_field] || model_opts[:type_field] || :type
       end
+
+      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.0'
+    VERSION = '0.2.3'
   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.1', '>= 0.1.0'
+  spec.add_dependency 'type_balancer', '~> 0.1', '>= 0.1.4'
 
   # 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.0
+  version: 0.2.3
 platform: ruby
 authors:
 - Carl Smith
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-04-27 00:00:00.000000000 Z
+date: 2025-04-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -59,7 +59,7 @@ dependencies:
         version: '0.1'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.1.0
+        version: 0.1.4
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -69,7 +69,7 @@ dependencies:
         version: '0.1'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.1.0
+        version: 0.1.4
 description: Provides Rails integration for the type_balancer gem
 email:
 - carl@llwebconsulting.com
@@ -77,12 +77,93 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".rspec"
 - ".rubocop.yml"
 - CHANGELOG.md
 - CODE_OF_CONDUCT.md
 - LICENSE.txt
 - README.md
 - Rakefile
+- example/.dockerignore
+- example/.rspec
+- example/.rubocop.yml
+- example/Dockerfile
+- example/Gemfile
+- example/Gemfile.lock
+- example/README.md
+- example/Rakefile
+- example/app/assets/images/.keep
+- example/app/assets/stylesheets/application.css
+- example/app/controllers/application_controller.rb
+- example/app/controllers/concerns/.keep
+- example/app/controllers/contents_controller.rb
+- example/app/controllers/posts_controller.rb
+- example/app/helpers/application_helper.rb
+- example/app/helpers/contents_helper.rb
+- example/app/helpers/posts_helper.rb
+- example/app/jobs/application_job.rb
+- example/app/mailers/application_mailer.rb
+- example/app/models/application_record.rb
+- example/app/models/concerns/.keep
+- example/app/models/content.rb
+- example/app/models/post.rb
+- example/app/views/contents/balance_by_category.html.erb
+- example/app/views/contents/balance_by_content_type.html.erb
+- example/app/views/layouts/application.html.erb
+- example/app/views/layouts/mailer.html.erb
+- example/app/views/layouts/mailer.text.erb
+- example/app/views/posts/balance_by_category.html.erb
+- example/app/views/posts/index.html.erb
+- example/app/views/pwa/manifest.json.erb
+- example/app/views/pwa/service-worker.js
+- example/bin/brakeman
+- example/bin/dev
+- example/bin/docker-entrypoint
+- example/bin/rails
+- example/bin/rake
+- example/bin/rubocop
+- example/bin/setup
+- example/bin/thrust
+- example/config.ru
+- example/config/application.rb
+- example/config/boot.rb
+- example/config/cable.yml
+- example/config/credentials.yml.enc
+- example/config/database.yml
+- example/config/environment.rb
+- example/config/environments/development.rb
+- example/config/environments/production.rb
+- example/config/environments/test.rb
+- example/config/initializers/assets.rb
+- example/config/initializers/content_security_policy.rb
+- example/config/initializers/filter_parameter_logging.rb
+- example/config/initializers/inflections.rb
+- example/config/locales/en.yml
+- example/config/master.key
+- example/config/puma.rb
+- example/config/routes.rb
+- example/config/storage.yml
+- example/db/migrate/20250427174733_create_posts.rb
+- example/db/migrate/20250427174747_create_contents.rb
+- example/db/schema.rb
+- example/db/seeds.rb
+- example/lib/tasks/.keep
+- example/lib/tasks/dev_fixtures.rake
+- example/script/.keep
+- example/spec/controllers/contents_controller_spec.rb
+- example/spec/controllers/posts_controller_spec.rb
+- example/spec/features/contents_balancing_spec.rb
+- example/spec/features/posts_balancing_spec.rb
+- example/spec/models/content_spec.rb
+- example/spec/models/post_spec.rb
+- example/spec/rails_helper.rb
+- example/spec/spec_helper.rb
+- example/storage/.keep
+- example/storage/development.sqlite3
+- example/storage/test.sqlite3
+- example/test/fixtures/contents.yml
+- example/test/fixtures/posts.yml
+- example/vendor/.keep
 - lib/generators/type_balancer/install/install_generator.rb
 - lib/generators/type_balancer/install/templates/type_balancer.rb.erb
 - lib/type_balancer/rails.rb