type_balancer 0.1.4 → 0.2.1

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,58 @@
+# frozen_string_literal: true
+
+module TypeBalancer
+  module Strategies
+    # Base class for all balancing strategies
+    class BaseStrategy
+      def initialize(items:, type_field:, types: nil, type_order: nil)
+        @items = items
+        @type_field = type_field
+        @types = types
+        @type_order = type_order
+      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
+        if @type_order
+          # First include ordered types that exist in the items
+          ordered = @type_order & types
+          # Then append any remaining types that weren't in the order
+          ordered + (types - @type_order)
+        else
+          # Use default order if no custom order provided
+          DEFAULT_TYPE_ORDER.select { |type| types.include?(type) } + (types - DEFAULT_TYPE_ORDER)
+        end
+      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,199 @@
+# frozen_string_literal: true
+
+require_relative 'base_strategy'
+
+module TypeBalancer
+  module Strategies
+    # Implements an efficient sliding window approach for balancing items
+    # This strategy uses array-based indexing and pre-calculated ratios for optimal performance
+    class SlidingWindowStrategy < BaseStrategy
+      DEFAULT_BATCH_SIZE = 1000
+
+      # rubocop:disable Metrics/ParameterLists
+      def initialize(items:, type_field:, types: nil, type_order: nil, window_size: 10, batch_size: DEFAULT_BATCH_SIZE)
+        super(items: items, type_field: type_field, types: types, type_order: type_order)
+        @window_size = window_size
+        @batch_size  = batch_size
+        @types       = types || extract_types
+      end
+      # rubocop:enable Metrics/ParameterLists
+
+      def balance
+        return [] if @items.empty?
+
+        validate_items!
+        return @items.dup if single_type?
+
+        @type_queues = build_type_queues
+        @type_ratios = calculate_type_ratios
+
+        if @items.size > @batch_size
+          process_large_collection
+        else
+          process_single_batch
+        end
+      end
+
+      private
+
+      def single_type?
+        @items.map { |item| item[@type_field].to_s }.uniq.one?
+      end
+
+      def build_type_queues
+        queues = {}
+        ordered_types = @type_order || @types
+        ordered_types.each { |t| queues[t] = [] }
+
+        @items.each_with_index do |item, idx|
+          t = item[@type_field].to_s
+          queues[t] << idx if queues.key?(t)
+        end
+
+        queues
+      end
+
+      def calculate_type_ratios
+        total = @items.size.to_f
+        @type_queues.transform_values { |inds| inds.size / total }
+      end
+
+      def process_large_collection
+        result       = Array.new(@items.size)
+        type_indices = initialize_type_indices
+
+        (0...@items.size).step(@batch_size) do |start_idx|
+          end_idx = [start_idx + @batch_size, @items.size].min
+          process_batch_range(result, type_indices, start_idx, end_idx)
+        end
+
+        result.compact
+      end
+
+      def process_single_batch
+        result = Array.new(@items.size)
+        process_batch_range(result, initialize_type_indices, 0, @items.size)
+        result.compact
+      end
+
+      def initialize_type_indices
+        @type_queues.transform_values { 0 }
+      end
+
+      def process_batch_range(result, type_indices, start_idx, end_idx)
+        window_start = start_idx
+
+        while window_start < end_idx
+          window_size = compute_window_size(window_start, end_idx)
+          positions   = calculate_window_positions(window_size)
+          apply_window_positions(positions, window_start, window_size, result, type_indices)
+          window_start += window_size
+        end
+
+        fill_gaps(result, type_indices, start_idx, end_idx)
+      end
+
+      def compute_window_size(start_pos, end_pos)
+        [[start_pos + @window_size, end_pos].min - start_pos, 1].max
+      end
+
+      def calculate_window_positions(window_size)
+        WindowSlotCalculator.new(@type_ratios, @type_order).calculate(window_size)
+      end
+
+      def apply_window_positions(positions, start_pos, size, result, type_indices)
+        ordered_types = @type_order || @type_queues.keys
+        ordered_types.each do |type|
+          next unless positions[type]
+
+          positions[type].times do
+            break if type_indices[type] >= @type_queues[type].size
+
+            pos = find_next_position(result, start_pos, start_pos + size)
+            break unless pos
+
+            result[pos] = @items[@type_queues[type][type_indices[type]]]
+            type_indices[type] += 1
+          end
+        end
+      end
+
+      def find_next_position(result, start_pos, end_pos)
+        (start_pos...end_pos).find { |i| result[i].nil? }
+      end
+
+      def fill_gaps(result, type_indices, start_idx, end_idx)
+        ordered_types = @type_order || @type_queues.keys
+
+        (start_idx...end_idx).each do |i|
+          next unless result[i].nil?
+
+          ordered_types.each do |type|
+            next unless @type_queues[type] && type_indices[type] < @type_queues[type].size
+
+            result[i] = @items[@type_queues[type][type_indices[type]]]
+            type_indices[type] += 1
+            break
+          end
+        end
+      end
+
+      class WindowSlotCalculator
+        def initialize(type_ratios, type_order)
+          @type_ratios = type_ratios
+          @type_order  = type_order
+        end
+
+        def calculate(window_size)
+          slots = build_initial_slots(window_size)
+          distribute_remaining_slots(slots)
+          slots
+        end
+
+        private
+
+        def build_initial_slots(window_size)
+          slots             = {}
+          remaining_ratio   = 1.0
+          @remaining_slots  = window_size
+
+          ordered_types.each do |t|
+            ratio  = @type_ratios[t] || 0
+            target = calculate_target(window_size, ratio, remaining_ratio)
+            slots[t] = target
+            @remaining_slots -= target
+            remaining_ratio -= ratio
+          end
+
+          slots
+        end
+
+        def calculate_target(size, ratio, rem_ratio)
+          tgt = (size * (ratio / rem_ratio)).floor
+          tgt = [tgt, @remaining_slots].min
+          tgt = 1 if ratio.positive? && tgt.zero? && @remaining_slots.positive?
+          tgt
+        end
+
+        def distribute_remaining_slots(slots)
+          return if @remaining_slots <= 0
+
+          types = sorted_distribution_types
+          @remaining_slots.times { |i| slots[types[i % types.size]] += 1 }
+        end
+
+        def ordered_types
+          @type_order || @type_ratios.keys
+        end
+
+        def sorted_distribution_types
+          if @type_order
+            @type_order & @type_ratios.keys
+          else
+            @type_ratios.sort_by { |_t, r| -r }.map(&:first)
+          end
+        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/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module TypeBalancer
-  VERSION = '0.1.4'
+  VERSION = '0.2.1'
 end

data/lib/type_balancer.rb

@@ -1,13 +1,15 @@
 # frozen_string_literal: true
 
 require 'type_balancer/version'
-require 'type_balancer/calculator'
 require_relative 'type_balancer/balancer'
 require_relative 'type_balancer/ratio_calculator'
 require_relative 'type_balancer/batch_processing'
-require 'type_balancer/position_calculator'
+require_relative 'type_balancer/position_calculator'
 require_relative 'type_balancer/type_extractor'
 require_relative 'type_balancer/type_extractor_registry'
+require_relative 'type_balancer/strategies/base_strategy'
+require_relative 'type_balancer/strategies/sliding_window_strategy'
+require_relative 'type_balancer/strategy_factory'
 
 module TypeBalancer
   class Error < StandardError; end
@@ -16,22 +18,34 @@ module TypeBalancer
   class EmptyCollectionError < Error; end
   class InvalidTypeError < Error; end
 
+  # Register default strategies
+  StrategyFactory.register(:sliding_window, Strategies::SlidingWindowStrategy)
+  StrategyFactory.default_strategy = :sliding_window
+
   # Load Ruby implementations
   require_relative 'type_balancer/distribution_calculator'
   require_relative 'type_balancer/ordered_collection_manager'
-  require_relative 'type_balancer/alternating_filler'
-  require_relative 'type_balancer/sequential_filler'
+  require_relative 'type_balancer/type_extractor'
+  require_relative 'type_balancer/type_extractor_registry'
+  require_relative 'type_balancer/ratio_calculator'
+  require_relative 'type_balancer/position_calculator'
   require_relative 'type_balancer/distributor'
+  require_relative 'type_balancer/sequential_filler'
+  require_relative 'type_balancer/alternating_filler'
+  require_relative 'type_balancer/balancer'
+  require_relative 'type_balancer/batch_processing'
+  require_relative 'type_balancer/calculator'
 
   def self.calculate_positions(total_count:, ratio:, available_items: nil)
-    Distributor.calculate_target_positions(
+    PositionCalculator.calculate_positions(
       total_count: total_count,
       ratio: ratio,
-      available_positions: available_items
+      available_items: available_items
     )
   end
 
-  def self.balance(items, type_field: :type, type_order: nil)
+  # rubocop:disable Metrics/ParameterLists
+  def self.balance(items, type_field: :type, type_order: nil, strategy: nil, window_size: nil, **strategy_options)
     # Input validation
     raise EmptyCollectionError, 'Collection cannot be empty' if items.empty?
 
@@ -44,12 +58,23 @@ module TypeBalancer
       raise Error, "Cannot access type field '#{type_field}': #{e.message}"
     end
 
-    # Initialize balancer with type order and type field
-    balancer = Balancer.new(types, type_field: type_field, type_order: type_order)
+    # Merge window_size into strategy_options if provided
+    strategy_options = strategy_options.merge(window_size: window_size) if window_size
+
+    # Create calculator with strategy options
+    calculator = Calculator.new(
+      items,
+      type_field: type_field,
+      types: type_order || types,
+      type_order: type_order,
+      strategy: strategy,
+      **strategy_options
+    )
 
     # Balance items
-    balancer.call(items)
+    calculator.call
   end
+  # rubocop:enable Metrics/ParameterLists
 
   # Backward compatibility methods
   def self.extract_types(items, type_field)

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: type_balancer
 version: !ruby/object:Gem::Version
-  version: 0.1.4
+  version: 0.2.1
 platform: ruby
 authors:
 - Carl Smith
 bindir: exe
 cert_chain: []
-date: 2025-04-29 00:00:00.000000000 Z
+date: 2025-05-01 00:00:00.000000000 Z
 dependencies: []
 description: Balances types in collections by ensuring each type appears a similar
   number of times
@@ -43,18 +43,24 @@ files:
 - docs/calculate_positions.md
 - docs/quality.md
 - examples/balance_test_data.yml
+- examples/large_scale_balance_test.rb
 - examples/quality.rb
 - lib/type_balancer.rb
 - lib/type_balancer/alternating_filler.rb
 - lib/type_balancer/balancer.rb
 - lib/type_balancer/batch_processing.rb
 - lib/type_balancer/calculator.rb
+- lib/type_balancer/configuration.rb
 - lib/type_balancer/distribution_calculator.rb
 - lib/type_balancer/distributor.rb
 - lib/type_balancer/ordered_collection_manager.rb
 - lib/type_balancer/position_calculator.rb
 - lib/type_balancer/ratio_calculator.rb
 - lib/type_balancer/sequential_filler.rb
+- lib/type_balancer/strategies.rb
+- lib/type_balancer/strategies/base_strategy.rb
+- lib/type_balancer/strategies/sliding_window_strategy.rb
+- lib/type_balancer/strategy_factory.rb
 - lib/type_balancer/type_extractor.rb
 - lib/type_balancer/type_extractor_registry.rb
 - lib/type_balancer/version.rb