type_balancer 0.1.3 → 0.2.0

data/examples/quality.rb

@@ -23,6 +23,8 @@ class QualityChecker
     check_available_positions_edge_cases
     check_balance_method_robust
     check_real_world_feed
+    check_custom_type_field
+    check_strategy_system
 
     print_summary
     exit(@issues.empty? ? 0 : 1)
@@ -328,6 +330,97 @@ class QualityChecker
     puts "  Balanced items with custom order: #{ordered_result.map { |i| i[:type] }.inspect}"
   end
 
+  def check_custom_type_field
+    @examples_run += 1
+    puts "\nCustom Type Field Example:"
+    data = [
+      { category: 'A', payload: 1 },
+      { category: 'B', payload: 2 },
+      { category: 'C', payload: 3 },
+      { category: 'A', payload: 4 }
+    ]
+    balanced = TypeBalancer.balance(data, type_field: :category)
+    found = balanced.map { |i| i[:category] }.uniq.sort
+    expected = %w[A B C]
+    if found == expected
+      @examples_passed += 1
+      puts "#{GREEN}Custom field respected: #{found.inspect}#{RESET}"
+    else
+      record_issue("Expected #{expected.inspect}, got #{found.inspect}")
+      puts "#{RED}Custom field test failed: #{found.inspect}#{RESET}"
+    end
+    print_section_table('custom_type_field', 1, found == expected ? 1 : 0)
+  end
+
+  def check_strategy_system
+    puts "\n#{YELLOW}Strategy System Tests:#{RESET}"
+    @section_examples_run = 0
+    @section_examples_passed = 0
+
+    # Test default strategy
+    @examples_run += 1
+    @section_examples_run += 1
+    items = [
+      { type: 'video', id: 1 },
+      { type: 'image', id: 2 },
+      { type: 'video', id: 3 }
+    ]
+    result = TypeBalancer.balance(items, type_field: :type)
+    if result.size == items.size && result.map { |i| i[:id] }.sort == [1, 2, 3]
+      @examples_passed += 1
+      @section_examples_passed += 1
+      puts "#{GREEN}Default strategy test passed#{RESET}"
+    else
+      record_issue("Default strategy test failed: unexpected result #{result.inspect}")
+      puts "#{RED}Default strategy test failed#{RESET}"
+    end
+
+    # Test sliding window strategy with custom window size
+    @examples_run += 1
+    @section_examples_run += 1
+    items = [
+      { type: 'video', id: 1 },
+      { type: 'image', id: 2 },
+      { type: 'video', id: 3 },
+      { type: 'image', id: 4 }
+    ]
+    result = TypeBalancer.balance(items, type_field: :type, strategy: :sliding_window, window_size: 2)
+    if result.size == items.size && 
+       result[0..1].map { |i| i[:type] }.uniq.size == 2 # First window has both types
+      @examples_passed += 1
+      @section_examples_passed += 1
+      puts "#{GREEN}Sliding window strategy with custom window size test passed#{RESET}"
+    else
+      record_issue("Sliding window strategy test failed: unexpected result #{result.inspect}")
+      puts "#{RED}Sliding window strategy with custom window size test failed#{RESET}"
+    end
+
+    # Test strategy with custom type order
+    @examples_run += 1
+    @section_examples_run += 1
+    items = [
+      { type: 'video', id: 1 },
+      { type: 'image', id: 2 },
+      { type: 'article', id: 3 }
+    ]
+    result = TypeBalancer.balance(
+      items,
+      type_field: :type,
+      strategy: :sliding_window,
+      types: %w[image video article]
+    )
+    if result.size == items.size && result.first[:type] == 'image'
+      @examples_passed += 1
+      @section_examples_passed += 1
+      puts "#{GREEN}Strategy with custom type order test passed#{RESET}"
+    else
+      record_issue("Strategy with custom type order test failed: unexpected result #{result.inspect}")
+      puts "#{RED}Strategy with custom type order test failed#{RESET}"
+    end
+
+    print_section_table('strategy_system')
+  end
+
   def print_summary
     puts "\n#{'-' * 50}"
     puts 'Quality Check Summary:'

data/lib/type_balancer/balancer.rb

@@ -3,6 +3,7 @@
 require_relative 'ratio_calculator'
 require_relative 'batch_processing'
 require_relative 'position_calculator'
+require_relative 'type_extractor_registry'
 
 module TypeBalancer
   # Handles balancing of items across batches based on type ratios
@@ -10,9 +11,11 @@ module TypeBalancer
     # Initialize a new Balancer instance
     #
     # @param types [Array<String>, nil] Optional types
+    # @param type_field [Symbol] Field to use for type extraction (default: :type)
     # @param type_order [Array<String>, nil] Optional order of types
-    def initialize(types = nil, type_order: nil)
+    def initialize(types = nil, type_field: :type, type_order: nil)
       @types = Array(types) if types
+      @type_field = type_field
       @type_order = type_order
       validate_types! if @types
     end
@@ -23,7 +26,18 @@ module TypeBalancer
     # @return [Array] Balanced items
     def call(collection)
       validate_collection!(collection)
-      items_by_type = group_items_by_type(collection)
+      extractor = TypeExtractorRegistry.get(@type_field)
+
+      begin
+        items_by_type = extractor.group_by_type(collection)
+      rescue TypeBalancer::Error => e
+        raise TypeBalancer::Error, "Cannot access type field '#{@type_field}': #{e.message}"
+      end
+
+      # Remove nil types and validate
+      items_by_type.delete(nil)
+      raise TypeBalancer::Error, "Cannot access type field '#{@type_field}'" if items_by_type.empty?
+
       validate_types_in_collection!(items_by_type)
 
       target_counts = calculate_target_counts(items_by_type)
@@ -70,24 +84,7 @@ module TypeBalancer
       raise TypeBalancer::Error, "Invalid type(s): #{invalid_types.join(', ')}" if invalid_types.any?
     end
 
-    def group_items_by_type(collection)
-      collection.group_by do |item|
-        extract_type(item)
-      end
-    end
-
-    def extract_type(item)
-      return item[:type] || item['type'] || raise(TypeBalancer::Error, 'Cannot access type field') if item.is_a?(Hash)
-
-      begin
-        item.type
-      rescue NoMethodError
-        raise TypeBalancer::Error, 'Cannot access type field'
-      end
-    end
-
     def calculate_target_counts(items_by_type)
-      items_by_type.values.sum(&:size)
       items_by_type.transform_values(&:size)
     end
 

data/lib/type_balancer/calculator.rb

@@ -1,5 +1,9 @@
 # frozen_string_literal: true
 
+require_relative 'strategy_factory'
+require_relative 'strategies/base_strategy'
+require_relative 'strategies/sliding_window_strategy'
+
 module TypeBalancer
   # Handles calculation of positions for balanced item distribution
   class PositionCalculator
@@ -80,6 +84,7 @@ module TypeBalancer
 
       def calculate_evenly_spaced_positions(total_count, target_count, ratio)
         return [0] if target_count == 1
+        return handle_two_positions_in_three_slots if target_count == 2 && total_count == 3
         return handle_two_thirds_case(total_count) if two_thirds_ratio?(ratio, total_count)
 
         (0...target_count).map do |i|
@@ -95,6 +100,10 @@ module TypeBalancer
         [0, 1]
       end
 
+      def handle_two_positions_in_three_slots
+        [0, 1]
+      end
+
       def valid_inputs?(total_count, ratio)
         total_count >= 0 && ratio >= 0 && ratio <= 1.0
       end
@@ -105,114 +114,41 @@ module TypeBalancer
   class Calculator
     DEFAULT_TYPE_ORDER = %w[video image strip article].freeze
 
-    def initialize(items, type_field: :type, types: nil)
+    def initialize(items, type_field: :type, types: nil, strategy: nil, **strategy_options)
       raise ArgumentError, 'Items cannot be nil' if items.nil?
       raise ArgumentError, 'Type field cannot be nil' if type_field.nil?
 
       @items = items
       @type_field = type_field
-      @types = types || extract_types
+      @types = types
+      @strategy_name = strategy
+      @strategy_options = strategy_options
     end
 
     def call
       return [] if @items.empty?
 
-      validate_items!
-
-      items_by_type = @types.map { |type| @items.select { |item| item[@type_field].to_s == type } }
-
-      # Calculate target positions for each type
-      target_positions = calculate_target_positions(items_by_type)
-
-      # Place items at their target positions
-      place_items_at_positions(items_by_type, target_positions)
+      # Create strategy instance
+      strategy = StrategyFactory.create(
+        @strategy_name,
+        items: @items,
+        type_field: @type_field,
+        types: @types || extract_types,
+        **@strategy_options
+      )
+
+      # Balance items using strategy
+      strategy.balance
     end
 
     private
 
-    def validate_items!
-      @items.each do |item|
-        raise ArgumentError, 'All items must have a type field' unless item.key?(@type_field)
-        raise ArgumentError, 'Type values cannot be empty' if item[@type_field].to_s.strip.empty?
-      end
-    end
-
     def extract_types
       types = @items.map { |item| item[@type_field].to_s }.uniq
       DEFAULT_TYPE_ORDER.select { |type| types.include?(type) } + (types - DEFAULT_TYPE_ORDER)
     end
-
-    def calculate_target_positions(items_by_type)
-      total_count = @items.size
-      available_positions = (0...total_count).to_a
-
-      items_by_type.map.with_index do |_items, index|
-        ratio = calculate_ratio(items_by_type.size, index)
-        target_count = (total_count * ratio).round
-
-        # Calculate positions based on ratio and total count
-        if target_count == 1
-          [index]
-        else
-          # For better distribution, calculate positions based on available slots
-          step = available_positions.size.fdiv(target_count)
-          positions = (0...target_count).map do |i|
-            pos_index = (i * step).round
-            available_positions[pos_index]
-          end
-
-          # Remove used positions from available ones
-          positions.each { |pos| available_positions.delete(pos) }
-          positions
-        end
-      end
-    end
-
-    def calculate_ratio(type_count, index)
-      case type_count
-      when 1 then 1.0
-      when 2 then index.zero? ? 0.6 : 0.4
-      else
-        # For 3+ types: first type gets 0.4, rest split remaining 0.6 evenly
-        remaining = (0.6 / (type_count - 1).to_f).round(6)
-        index.zero? ? 0.4 : remaining
-      end
-    end
-
-    def place_items_at_positions(items_by_type, target_positions)
-      result = Array.new(@items.size)
-      used_items = place_items_at_target_positions(items_by_type, target_positions, result)
-      fill_empty_slots(result, used_items)
-      result.compact
-    end
-
-    def place_items_at_target_positions(items_by_type, target_positions, result)
-      used_items = []
-      items_by_type.each_with_index do |items, type_index|
-        positions = target_positions[type_index] || []
-        place_type_items(items, positions, result, used_items)
-      end
-      used_items
-    end
-
-    def place_type_items(items, positions, result, used_items)
-      items.take(positions.size).each_with_index do |item, item_index|
-        pos = positions[item_index]
-        next unless pos && result[pos].nil?
-
-        result[pos] = item
-        used_items << item
-      end
-    end
-
-    def fill_empty_slots(result, used_items)
-      remaining_items = @items - used_items
-      empty_slots = result.each_index.select { |i| result[i].nil? }
-      empty_slots.zip(remaining_items).each do |slot, item|
-        break unless item
-
-        result[slot] = item
-      end
-    end
   end
 end
+
+# Register default strategy
+TypeBalancer::StrategyFactory.register(:sliding_window, TypeBalancer::Strategies::SlidingWindowStrategy)

data/lib/type_balancer/distributor.rb

@@ -6,29 +6,82 @@ module TypeBalancer
       # Validate inputs
       return [] if total_count <= 0 || ratio <= 0 || ratio > 1
 
-      # Calculate target count and round down for specific ratios
-      target_count = if ratio <= 0.34
-                       1 # For ratios <= 0.34, always use 1 position
-                     elsif ratio <= 0.67
-                       2 # For ratios <= 0.67, always use 2 positions
-                     else
-                       (total_count * ratio).ceil
-                     end
+      # Calculate base target count
+      target_count = (total_count * ratio).ceil
+
+      # Special case for 3 slots
+      if total_count == 3
+        target_count = if ratio <= 0.34
+                         1
+                       elsif ratio <= 0.67
+                         2
+                       else
+                         3
+                       end
+      end
 
       return [] if target_count.zero?
       return (0...total_count).to_a if target_count >= total_count
 
-      # Special case for 3 slots
-      if total_count == 3
+      if available_positions
+        # Filter out invalid positions and sort them
+        valid_positions = available_positions.select { |pos| pos >= 0 && pos < total_count }.sort
+        return [] if valid_positions.empty?
+
+        # For single target position, use first available
+        return [valid_positions.first] if target_count == 1
+
+        # For two positions
+        if target_count == 2
+          # Special case for three slots
+          if total_count == 3
+            return [valid_positions[0], valid_positions[1]] if valid_positions.size >= 2
+
+            return [valid_positions.first, valid_positions.first + 1]
+          end
+
+          # Special case for invalid positions that go beyond total_count
+          if available_positions.any? { |pos| pos >= total_count }
+            valid_positions = available_positions.select { |pos| pos >= 0 }.sort
+            return [valid_positions.first, valid_positions.last]
+          end
+
+          # Otherwise use first and last
+          return [valid_positions.first, valid_positions.last]
+        end
+
+        # If we have fewer or equal positions than needed, use all available up to target_count
+        return valid_positions if valid_positions.size <= target_count
+
+        # For more positions, take the first N positions where N is target_count
+        return valid_positions.first(target_count) if target_count <= 3
+
+        # For larger target counts, distribute evenly
+        target_positions = []
+        step = (valid_positions.size - 1).fdiv(target_count - 1)
+        (0...target_count).each do |i|
+          index = (i * step).round
+          target_positions << valid_positions[index]
+        end
+        target_positions
+      else
+        # Handle single target position
         return [0] if target_count == 1
-        return [0, 1] if target_count == 2
-      end
 
-      TypeBalancer::PositionCalculator.calculate_positions(
-        total_count: total_count,
-        ratio: ratio,
-        available_items: available_positions
-      )
+        # For two positions
+        if target_count == 2
+          # Special case for three slots
+          return [0, 1] if total_count == 3
+
+          # Otherwise use first and last
+          return [0, total_count - 1]
+        end
+
+        # Calculate evenly spaced positions for multiple targets
+        (0...target_count).map do |i|
+          ((total_count - 1) * i.fdiv(target_count - 1)).round
+        end
+      end
     end
   end
 end

data/lib/type_balancer/strategies/base_strategy.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module TypeBalancer
+  module Strategies
+    # Base class for all balancing strategies
+    class BaseStrategy
+      def initialize(items:, type_field:, types: nil)
+        @items = items
+        @type_field = type_field
+        @types = types
+      end
+
+      # Interface method that all strategies must implement
+      def balance
+        raise NotImplementedError, 'Strategies must implement #balance'
+      end
+
+      protected
+
+      def validate_items!
+        @items.each do |item|
+          raise ArgumentError, 'All items must have a type field' unless item.key?(@type_field)
+          raise ArgumentError, 'Type values cannot be empty' if item[@type_field].to_s.strip.empty?
+        end
+      end
+
+      def extract_types
+        types = @items.map { |item| item[@type_field].to_s }.uniq
+        DEFAULT_TYPE_ORDER.select { |type| types.include?(type) } + (types - DEFAULT_TYPE_ORDER)
+      end
+
+      def group_items_by_type
+        # First, create a hash to store items by type while preserving order
+        type_queues = {}
+        @types.each { |type| type_queues[type] = [] }
+
+        # Add items to their respective queues in order
+        @items.each do |item|
+          type = item[@type_field].to_s
+          type_queues[type] << item if type_queues.key?(type)
+        end
+
+        type_queues
+      end
+
+      DEFAULT_TYPE_ORDER = %w[video image strip article].freeze
+    end
+  end
+end

data/lib/type_balancer/strategies/sliding_window_strategy.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+require_relative 'base_strategy'
+
+module TypeBalancer
+  module Strategies
+    # Implements a sliding window approach to balance items
+    class SlidingWindowStrategy < BaseStrategy
+      def initialize(items:, type_field:, types: nil, window_size: 10)
+        super(items: items, type_field: type_field, types: types)
+        @window_size = window_size
+        @types = types || extract_types
+      end
+
+      def balance
+        return [] if @items.empty?
+
+        validate_items!
+        return @items.dup if group_items_by_type.size == 1
+
+        type_queues   = group_items_by_type
+        type_ratios   = calculate_type_ratios(type_queues)
+
+        process_windows(type_queues, type_ratios)
+      end
+
+      private
+
+      def calculate_type_ratios(type_queues)
+        total_items = @items.size.to_f
+        type_queues.transform_values { |list| list.size / total_items }
+      end
+
+      def process_windows(type_queues, type_ratios)
+        result     = []
+        used_items = Set.new
+
+        until result.size == @items.size
+          size   = next_window_size(result)
+          window = balance_window(type_queues, type_ratios, size, used_items)
+
+          if window.empty?
+            append_remaining(result, used_items)
+          else
+            window.each do |item|
+              next if used_items.include?(item)
+
+              result << item
+              used_items.add(item)
+            end
+          end
+        end
+
+        result
+      end
+
+      def next_window_size(result)
+        (@items.size - result.size).clamp(1, @window_size)
+      end
+
+      def append_remaining(result, used_items)
+        @items.each do |item|
+          next if used_items.include?(item)
+
+          result << item
+          used_items.add(item)
+        end
+      end
+
+      def balance_window(type_queues, type_ratios, window_size, used_items)
+        window_items   = []
+        target_counts  = calculate_window_targets(type_ratios, window_size)
+        current_counts = Hash.new(0)
+
+        while window_items.size < window_size
+          type_to_add = find_next_type(type_ratios, current_counts, target_counts, type_queues, used_items)
+          break unless type_to_add
+
+          next_item = type_queues[type_to_add].find { |i| !used_items.include?(i) }
+          break unless next_item
+
+          window_items << next_item
+          current_counts[type_to_add] += 1
+        end
+
+        window_items
+      end
+
+      def calculate_window_targets(type_ratios, window_size)
+        targets = type_ratios.transform_values { |ratio| (window_size * ratio).floor }
+        ensure_minimum_representation(targets, type_ratios)
+        scale_down_if_needed(targets, window_size)
+        distribute_remaining_slots(targets, type_ratios, window_size)
+        targets
+      end
+
+      def find_next_type(type_ratios, current_counts, target_counts, type_queues, used_items)
+        current_ratios = compute_current_ratios(current_counts, type_ratios)
+        eligible = eligible_types(type_ratios, current_counts, target_counts, type_queues, used_items)
+        eligible.min_by { |t| (current_ratios[t] || 0) - type_ratios[t] }
+      end
+
+      def ensure_minimum_representation(targets, type_ratios)
+        type_ratios.each_key do |t|
+          targets[t] = 1 if type_ratios[t].positive? && targets[t] < 1
+        end
+      end
+
+      def scale_down_if_needed(targets, window_size)
+        total = targets.values.sum
+        return unless total > window_size
+
+        factor = window_size.to_f / total
+        targets.transform_values! { |count| (count * factor).floor }
+      end
+
+      def distribute_remaining_slots(targets, type_ratios, window_size)
+        remaining = window_size - targets.values.sum
+        return unless remaining.positive?
+
+        sorted = type_ratios.sort_by { |_t, r| -r }.map(&:first)
+        remaining.times { |i| targets[sorted[i % sorted.size]] += 1 }
+      end
+
+      def compute_current_ratios(current_counts, type_ratios)
+        total = current_counts.values.sum.to_f
+        return type_ratios.dup if total.zero?
+
+        current_counts.transform_values { |c| c / total }
+      end
+
+      def eligible_types(type_ratios, current_counts, target_counts, type_queues, used_items)
+        type_ratios.keys.select do |t|
+          type_queues[t].any? { |i| !used_items.include?(i) } &&
+            current_counts[t] < target_counts[t]
+        end
+      end
+    end
+  end
+end

data/lib/type_balancer/strategies.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module TypeBalancer
+  # Module containing all balancing strategies
+  module Strategies
+  end
+end

data/lib/type_balancer/strategy_factory.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module TypeBalancer
+  # Factory for creating and managing balancing strategies
+  class StrategyFactory
+    class << self
+      def create(strategy_name = nil, **)
+        strategy_name ||= default_strategy
+        strategy_class = find_strategy(strategy_name)
+
+        raise ArgumentError, "Unknown strategy: #{strategy_name}" unless strategy_class
+
+        strategy_class.new(**)
+      end
+
+      def register(name, strategy_class)
+        strategies[name.to_sym] = strategy_class
+      end
+
+      def default_strategy=(name)
+        raise ArgumentError, "Unknown strategy: #{name}" unless strategies.key?(name.to_sym)
+
+        @default_strategy = name.to_sym
+      end
+
+      def default_strategy
+        @default_strategy ||= :sliding_window
+      end
+
+      private
+
+      def strategies
+        @strategies ||= {}
+      end
+
+      def find_strategy(name)
+        strategies[name.to_sym]
+      end
+    end
+  end
+end

data/lib/type_balancer/type_extractor.rb

@@ -20,10 +20,15 @@ module TypeBalancer
       if item.respond_to?(@type_field)
         item.send(@type_field)
       elsif item.respond_to?(:[])
-        item[@type_field] || item[@type_field.to_s]
+        value = item[@type_field] || item[@type_field.to_s]
+        raise TypeBalancer::Error, "Cannot access type field '#{@type_field}' on item #{item.inspect}" if value.nil?
+
+        value
       else
-        raise Error, "Cannot access type field '#{@type_field}' on item #{item}"
+        raise TypeBalancer::Error, "Cannot access type field '#{@type_field}' on item #{item.inspect}"
       end
+    rescue NoMethodError, TypeError
+      raise TypeBalancer::Error, "Cannot access type field '#{@type_field}' on item #{item.inspect}"
     end
   end
 end