type_balancer 0.1.0 → 0.1.3

data/examples/quality.rb

@@ -1,8 +1,14 @@
 # frozen_string_literal: true
 
 require 'type_balancer'
+require 'yaml'
 
 class QualityChecker
+  GREEN = "\e[32m"
+  RED = "\e[31m"
+  YELLOW = "\e[33m"
+  RESET = "\e[0m"
+
   def initialize
     @issues = []
     @examples_run = 0
@@ -13,6 +19,9 @@ class QualityChecker
     check_basic_distribution
     check_available_items
     check_edge_cases
+    check_position_precision
+    check_available_positions_edge_cases
+    check_balance_method_robust
     check_real_world_feed
 
     print_summary
@@ -27,11 +36,15 @@ class QualityChecker
 
   def check_basic_distribution
     @examples_run += 1
+    @section_examples_run = 0 if !defined?(@section_examples_run)
+    @section_examples_passed = 0 if !defined?(@section_examples_passed)
+    @section_examples_run += 1
     puts "\nBasic Distribution Example:"
     positions = TypeBalancer.calculate_positions(total_count: 10, ratio: 0.3)
 
     if positions == [0, 5, 9]
       @examples_passed += 1
+      @section_examples_passed += 1
     else
       record_issue("Basic distribution positions #{positions.inspect} don't match expected [0, 5, 9]")
     end
@@ -47,6 +60,7 @@ class QualityChecker
 
   def check_available_items
     @examples_run += 1
+    @section_examples_run += 1
     puts "\nAvailable Items Example:"
     positions = TypeBalancer.calculate_positions(
       total_count: 10,
@@ -56,6 +70,7 @@ class QualityChecker
 
     if positions == [0, 1, 2]
       @examples_passed += 1
+      @section_examples_passed += 1
     else
       record_issue("Available items test returned #{positions.inspect} instead of expected [0, 1, 2]")
     end
@@ -68,111 +83,280 @@ class QualityChecker
 
     # Single item
     @examples_run += 1
+    @section_examples_run += 1
     single = TypeBalancer.calculate_positions(total_count: 1, ratio: 1.0)
     puts "Single item: #{single.inspect}"
     if single == [0]
       @examples_passed += 1
+      @section_examples_passed += 1
     else
       record_issue("Single item case returned #{single.inspect} instead of [0]")
     end
 
     # No items
     @examples_run += 1
+    @section_examples_run += 1
     none = TypeBalancer.calculate_positions(total_count: 100, ratio: 0.0)
     puts "No items needed: #{none.inspect}"
     if none == []
       @examples_passed += 1
+      @section_examples_passed += 1
     else
       record_issue("Zero ratio case returned #{none.inspect} instead of []")
     end
 
     # All items
     @examples_run += 1
+    @section_examples_run += 1
     all = TypeBalancer.calculate_positions(total_count: 5, ratio: 1.0)
     puts "All items needed: #{all.inspect}"
     if all == [0, 1, 2, 3, 4]
       @examples_passed += 1
+      @section_examples_passed += 1
     else
       record_issue("Full ratio case returned #{all.inspect} instead of [0, 1, 2, 3, 4]")
     end
+    print_section_table('calculate_positions')
   end
 
-  def check_real_world_feed
+  def check_position_precision
+    puts "\nPosition Precision Cases:"
+    
+    # Two positions in three slots
     @examples_run += 1
-    puts "\nReal World Example - Content Feed:"
-    feed_size = 20
+    @section_examples_run += 1
+    positions = TypeBalancer.calculate_positions(total_count: 3, ratio: 0.67)
+    puts "Two positions in three slots: #{positions.inspect}"
+    if positions == [0, 1]
+      @examples_passed += 1
+      @section_examples_passed += 1
+    else
+      record_issue("Two in three case returned #{positions.inspect} instead of [0, 1]")
+    end
 
-    # Track allocated positions
-    allocated_positions = []
-    content_positions = {}
+    # Single position in three slots
+    @examples_run += 1
+    @section_examples_run += 1
+    positions = TypeBalancer.calculate_positions(total_count: 3, ratio: 0.34)
+    puts "Single position in three slots: #{positions.inspect}"
+    if positions == [0]
+      @examples_passed += 1
+      @section_examples_passed += 1
+    else
+      record_issue("One in three case returned #{positions.inspect} instead of [0]")
+    end
+    print_section_table('calculate_positions')
+  end
 
-    # Calculate positions for each type
-    content_positions[:video] = TypeBalancer.calculate_positions(
-      total_count: feed_size,
-      ratio: 0.3,
-      available_items: (0..7).to_a - allocated_positions
-    )
-    allocated_positions += content_positions[:video]
+  def check_available_positions_edge_cases
+    puts "\nAvailable Positions Edge Cases:"
 
-    content_positions[:image] = TypeBalancer.calculate_positions(
-      total_count: feed_size,
-      ratio: 0.4,
-      available_items: (0..14).to_a - allocated_positions
+    # Single target with multiple available positions
+    @examples_run += 1
+    @section_examples_run += 1
+    positions = TypeBalancer.calculate_positions(
+      total_count: 5,
+      ratio: 0.2,
+      available_items: [1, 2, 3]
     )
-    allocated_positions += content_positions[:image]
+    puts "Single target with multiple available: #{positions.inspect}"
+    if positions == [1]
+      @examples_passed += 1
+      @section_examples_passed += 1
+    else
+      record_issue("Single target with multiple available returned #{positions.inspect} instead of [1]")
+    end
 
-    content_positions[:article] = TypeBalancer.calculate_positions(
-      total_count: feed_size,
-      ratio: 0.3,
-      available_items: (0..19).to_a - allocated_positions
+    # Two targets with multiple available positions
+    @examples_run += 1
+    @section_examples_run += 1
+    positions = TypeBalancer.calculate_positions(
+      total_count: 10,
+      ratio: 0.2,
+      available_items: [1, 3, 5]
     )
-
-    puts "\nContent Type Positions:"
-    content_positions.each do |type, pos|
-      puts "#{type}: #{pos.inspect}"
+    puts "Two targets with multiple available: #{positions.inspect}"
+    if positions == [1, 5]
+      @examples_passed += 1
+      @section_examples_passed += 1
+    else
+      record_issue("Two targets with multiple available returned #{positions.inspect} instead of [1, 5]")
     end
 
-    # Check for overlaps
-    all_positions = content_positions.values.compact.flatten
-    if all_positions == all_positions.uniq
-      puts "\nSuccess: No overlapping positions!"
+    # Exact match of available positions
+    @examples_run += 1
+    @section_examples_run += 1
+    positions = TypeBalancer.calculate_positions(
+      total_count: 10,
+      ratio: 0.3,
+      available_items: [2, 4, 6]
+    )
+    puts "Exact match of available positions: #{positions.inspect}"
+    if positions == [2, 4, 6]
       @examples_passed += 1
+      @section_examples_passed += 1
     else
-      overlaps = all_positions.group_by { |e| e }.select { |_, v| v.size > 1 }.keys
-      record_issue("Found overlapping positions at indices: #{overlaps.inspect}")
-      puts "\nWarning: Some positions overlap!"
+      record_issue("Exact match case returned #{positions.inspect} instead of [2, 4, 6]")
     end
+    print_section_table('calculate_positions')
+  end
 
-    # Verify distribution
-    puts "\nDistribution Stats:"
-    expected_counts = { video: 6, image: 8, article: 6 }
-    content_positions.each do |type, positions|
-      count = positions&.length || 0
-      percentage = (count.to_f / feed_size * 100).round(1)
-      puts "#{type}: #{count} items (#{percentage}% of feed)"
+  def check_balance_method_robust
+    puts "\n#{YELLOW}Robust Balance Method Tests:#{RESET}"
+    scenarios = YAML.load_file(File.expand_path('../balance_test_data.yml', __FILE__))
+    section_run = 0
+    section_passed = 0
+    scenarios.each do |scenario|
+      @examples_run += 1
+      section_run += 1
+      # Deep symbolize keys for all items in the scenario
+      items = (scenario['items'] || []).map { |item| deep_symbolize_keys(item) }
+      type_order = scenario['type_order']
+      expected_type_counts = scenario['expected_type_counts'] || {}
+      expected_first_type = scenario['expected_first_type']
 
-      if count != expected_counts[type]
-        record_issue("#{type} count #{count} doesn't match expected #{expected_counts[type]}")
+      # Test with and without type_order
+      [nil, type_order].uniq.each do |order|
+        label = order ? "with type_order #{order}" : "default order"
+        begin
+          # Special handling for the empty input case
+          if scenario['name'] =~ /empty/i
+            begin
+              if order
+                TypeBalancer.balance(items, type_field: :type, type_order: order)
+              else
+                TypeBalancer.balance(items, type_field: :type)
+              end
+              # If no exception, this is a failure
+              record_issue("#{scenario['name']} (#{label}): Expected exception for empty input, but none was raised")
+              puts "#{RED}#{scenario['name']} (#{label}): Expected exception for empty input, but none was raised#{RESET}"
+            rescue => e
+              if e.message =~ /Collection cannot be empty/
+                @examples_passed += 1
+                section_passed += 1
+                puts "#{GREEN}#{scenario['name']} (#{label}): Correctly raised exception for empty input#{RESET}"
+              else
+                record_issue("#{scenario['name']} (#{label}): Unexpected exception: #{e}")
+                puts "#{RED}#{scenario['name']} (#{label}): Unexpected exception: #{e}#{RESET}"
+              end
+            end
+            next
+          end
+          # Normal test logic for other cases
+          result = if order
+            TypeBalancer.balance(items, type_field: :type, type_order: order)
+          else
+            TypeBalancer.balance(items, type_field: :type)
+          end
+        rescue => e
+          record_issue("#{scenario['name']} (#{label}): Exception raised: #{e}")
+          puts "#{RED}#{scenario['name']} (#{label}): Exception raised: #{e}#{RESET}"
+          next
+        end
+        # Check type counts
+        type_counts = result.group_by { |i| i[:type] }.transform_values(&:size)
+        if expected_type_counts && !expected_type_counts.empty?
+          if type_counts != expected_type_counts
+            record_issue("#{scenario['name']} (#{label}): Type counts #{type_counts.inspect} do not match expected #{expected_type_counts.inspect}")
+            puts "#{RED}#{scenario['name']} (#{label}): Type counts #{type_counts.inspect} do not match expected #{expected_type_counts.inspect}#{RESET}"
+          else
+            @examples_passed += 1
+            section_passed += 1
+            puts "#{GREEN}#{scenario['name']} (#{label}): Passed#{RESET}"
+          end
+        end
+        # Check first type for custom order
+        if expected_first_type && order
+          if result.first && result.first[:type] != expected_first_type
+            record_issue("#{scenario['name']} (#{label}): First type #{result.first[:type]} does not match expected #{expected_first_type}")
+            puts "#{RED}#{scenario['name']} (#{label}): First type #{result.first[:type]} does not match expected #{expected_first_type}#{RESET}"
+          else
+            @examples_passed += 1
+            section_passed += 1
+            puts "#{GREEN}#{scenario['name']} (#{label}): Custom order respected#{RESET}"
+          end
+        end
+        puts "  Result: #{result.map { |i| i[:type] }.inspect}"
+        puts "  Type counts: #{type_counts.inspect}"
       end
     end
+    print_section_table('balance_method', section_run, section_passed)
+  end
+
+  # Helper to deeply symbolize keys in a hash
+  def deep_symbolize_keys(obj)
+    case obj
+    when Hash
+      obj.each_with_object({}) { |(k, v), h| h[k.to_sym] = deep_symbolize_keys(v) }
+    when Array
+      obj.map { |v| deep_symbolize_keys(v) }
+    else
+      obj
+    end
+  end
+
+  def check_real_world_feed
+    @examples_run += 1
+    puts "\n#{YELLOW}Real World Example - Content Feed:#{RESET}"
+    feed_size = 20
+    items = [
+      { type: 'video', id: 1 },
+      { type: 'video', id: 2 },
+      { type: 'video', id: 3 },
+      { type: 'image', id: 4 },
+      { type: 'image', id: 5 },
+      { type: 'image', id: 6 },
+      { type: 'article', id: 7 },
+      { type: 'article', id: 8 },
+      { type: 'article', id: 9 }
+    ]
+    # Test with custom type order
+    ordered_result = TypeBalancer.balance(
+      items,
+      type_field: :type,
+      type_order: %w[article image video]
+    )
+    if ordered_result.first[:type] == 'article'
+      @examples_passed += 1
+      puts "#{GREEN}Custom type order respected in real world feed#{RESET}"
+      print_section_table('real_world_feed', 1, 1)
+    else
+      record_issue("Custom type order not respected in real world feed")
+      puts "#{RED}Custom type order not respected in real world feed#{RESET}"
+      print_section_table('real_world_feed', 1, 0)
+    end
+    puts "  Balanced items with custom order: #{ordered_result.map { |i| i[:type] }.inspect}"
   end
 
   def print_summary
     puts "\n#{'-' * 50}"
     puts 'Quality Check Summary:'
     puts "Examples Run: #{@examples_run}"
-    puts "Examples Passed: #{@examples_passed}"
+    puts "Expectations Passed: #{@examples_passed}"
 
     if @issues.empty?
-      puts "\nAll quality checks passed! ✓"
+      puts "\n#{GREEN}All quality checks passed! ✓#{RESET}"
     else
-      puts "\nQuality check failed with #{@issues.size} issues:"
+      puts "\n#{RED}Quality check failed with #{@issues.size} issues:#{RESET}"
       @issues.each_with_index do |issue, index|
-        puts "#{index + 1}. #{issue}"
+        puts "#{RED}#{index + 1}. #{issue}#{RESET}"
       end
     end
     puts "#{'-' * 50}"
   end
+
+  # Print a summary table for a section
+  def print_section_table(section, run = @section_examples_run, passed = @section_examples_passed)
+    failed = run - passed
+    puts "\nSection: #{section}"
+    puts "-----------------------------"
+    puts "  #{GREEN}Passing: #{passed}#{RESET}"
+    puts "  #{RED}Failing: #{failed}#{RESET}"
+    puts "-----------------------------\n"
+    # Reset section counters for next section
+    @section_examples_run = 0
+    @section_examples_passed = 0
+  end
 end
 
 QualityChecker.new.run

data/lib/type_balancer/balancer.rb

@@ -1,126 +1,103 @@
 # frozen_string_literal: true
 
+require_relative 'ratio_calculator'
+require_relative 'batch_processing'
+require_relative 'position_calculator'
+
 module TypeBalancer
-  # Main class responsible for balancing items in a collection based on their types.
-  # It uses a distribution calculator to determine optimal positions for each type
-  # and a gap filler strategy to place items in the final sequence.
+  # Handles balancing of items across batches based on type ratios
   class Balancer
-    BATCH_SIZE = 500 # Process items in batches of 500 for better performance
-
-    def initialize(collection, type_field: :type, types: nil, distribution_calculator: nil)
-      @collection = collection
-      @type_field = type_field
-      @types = types || extract_types
-      @distribution_calculator = distribution_calculator || Distributor
+    # Initialize a new Balancer instance
+    #
+    # @param types [Array<String>, nil] Optional types
+    # @param type_order [Array<String>, nil] Optional order of types
+    def initialize(types = nil, type_order: nil)
+      @types = Array(types) if types
+      @type_order = type_order
+      validate_types! if @types
     end
 
-    def call
-      return [] if @collection.empty?
+    # Main entry point for balancing items
+    #
+    # @param collection [Array] Items to balance
+    # @return [Array] Balanced items
+    def call(collection)
+      validate_collection!(collection)
+      items_by_type = group_items_by_type(collection)
+      validate_types_in_collection!(items_by_type)
+
+      target_counts = calculate_target_counts(items_by_type)
+      available_positions = (0...collection.size).to_a
+
+      result = Array.new(collection.size)
+      sorted_types = sort_types(items_by_type.keys)
+
+      sorted_types.each do |type|
+        items = items_by_type[type]
+        target_count = target_counts[type]
+        ratio = target_count.to_f / collection.size
+        positions = PositionCalculator.calculate_positions(
+          total_count: collection.size,
+          ratio: ratio,
+          available_items: available_positions
+        )
+
+        positions.each_with_index do |pos, idx|
+          result[pos] = items[idx]
+        end
 
-      if @collection.size <= BATCH_SIZE
-        process_single_batch(@collection)
-      else
-        process_multiple_batches
+        # Remove used positions from available positions
+        available_positions -= positions
       end
+
+      result.compact
     end
 
     private
 
-    def process_single_batch(items)
-      # Group items by type
-      items_by_type = items.group_by { |item| get_type(item) }
-
-      # Calculate ratios based on type order and counts
-      ratios = calculate_ratios(items_by_type)
-
-      # Calculate positions for each type
-      positions_by_type = calculate_positions_by_type(items_by_type, ratios, items.size)
-
-      # Map items to their balanced positions
-      balanced_items = place_items_in_positions(items_by_type, positions_by_type, items.size)
-
-      # Fill any gaps with remaining items
-      fill_gaps(balanced_items, items)
+    def validate_types!
+      raise ArgumentError, 'Types cannot be empty' if @types.empty?
     end
 
-    def process_multiple_batches
-      result = []
-      @collection.each_slice(BATCH_SIZE) do |batch|
-        result.concat(process_single_batch(batch))
-      end
-      result
+    def validate_collection!(collection)
+      raise ArgumentError, 'Collection cannot be empty' if collection.empty?
     end
 
-    def calculate_positions_by_type(items_by_type, ratios, total_count)
-      positions_by_type = {}
-
-      @types.each_with_index do |type, index|
-        items = items_by_type[type] || []
-        ratio = ratios[index]
-        positions = @distribution_calculator.calculate_target_positions(total_count, items.size, ratio)
-        positions_by_type[type] = positions
-      end
+    def validate_types_in_collection!(items_by_type)
+      return unless @types
 
-      positions_by_type
+      invalid_types = items_by_type.keys - @types
+      raise TypeBalancer::Error, "Invalid type(s): #{invalid_types.join(', ')}" if invalid_types.any?
     end
 
-    def place_items_in_positions(items_by_type, positions_by_type, total_count)
-      balanced_items = Array.new(total_count)
-
-      @types.each do |type|
-        items = items_by_type[type] || []
-        positions = positions_by_type[type] || []
-
-        items.each_with_index do |item, index|
-          pos = positions[index]
-          next unless pos && pos < total_count && balanced_items[pos].nil?
-
-          balanced_items[pos] = item
-        end
+    def group_items_by_type(collection)
+      collection.group_by do |item|
+        extract_type(item)
       end
-
-      balanced_items
     end
 
-    def fill_gaps(balanced_items, original_items)
-      # Fill any gaps with remaining items
-      remaining_items = original_items.reject { |item| balanced_items.include?(item) }
-      empty_positions = balanced_items.each_index.select { |i| balanced_items[i].nil? }
-
-      empty_positions.each_with_index do |pos, idx|
-        break unless idx < remaining_items.size
+    def extract_type(item)
+      return item[:type] || item['type'] || raise(TypeBalancer::Error, 'Cannot access type field') if item.is_a?(Hash)
 
-        balanced_items[pos] = remaining_items[idx]
+      begin
+        item.type
+      rescue NoMethodError
+        raise TypeBalancer::Error, 'Cannot access type field'
       end
-
-      balanced_items.compact
     end
 
-    def calculate_ratios(_items_by_type)
-      case @types.size
-      when 1
-        [1.0]
-      when 2
-        [0.6, 0.4]
-      else
-        # First type gets 0.4, rest split remaining 0.6 evenly
-        remaining = (0.6 / (@types.size - 1).to_f).round(6)
-        [0.4] + Array.new(@types.size - 1, remaining)
-      end
+    def calculate_target_counts(items_by_type)
+      items_by_type.values.sum(&:size)
+      items_by_type.transform_values(&:size)
     end
 
-    def get_type(item)
-      if item.respond_to?(@type_field)
-        item.send(@type_field)
-      elsif item.respond_to?(:[])
-        item[@type_field] || item[@type_field.to_s]
-      else
-        raise Error, "Cannot access type field '#{@type_field}' on item #{item}"
-      end
-    end
+    def sort_types(types)
+      return types.sort unless @type_order
 
-    def extract_types
-      TypeBalancer.extract_types(@collection, @type_field)
+      types.sort_by do |type|
+        idx = @type_order.index(type)
+        idx || Float::INFINITY
+      end
     end
   end
 end

data/lib/type_balancer/batch_processing.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module TypeBalancer
+  class BatchProcessing
+    def initialize(batch_size)
+      @batch_size = batch_size
+    end
+
+    def create_batches(items_by_type, positions_by_type)
+      total_items = items_by_type.values.sum(&:size)
+      batches = []
+      current_batch = []
+
+      (0...total_items).each do |position|
+        type = find_type_for_position(position, positions_by_type)
+        current_batch << items_by_type[type].shift if type && !items_by_type[type].empty?
+
+        if current_batch.size >= @batch_size || position == total_items - 1
+          batches << current_batch unless current_batch.empty?
+          current_batch = []
+        end
+      end
+
+      batches
+    end
+
+    private
+
+    def find_type_for_position(position, positions_by_type)
+      positions_by_type.find do |_, positions|
+        positions.include?(position)
+      end&.first
+    end
+  end
+end