type_balancer 0.1.4 → 0.2.1

data/docs/balance.md

@@ -1,25 +1,124 @@
 # Detailed Documentation: `TypeBalancer.balance`
 
-`TypeBalancer.balance` is the main method for distributing items of different types across a sequence, ensuring optimal spacing and respecting type ratios. It is highly configurable and supports custom type fields and type orderings.
+`TypeBalancer.balance` is the main method for distributing items of different types across a sequence, ensuring optimal spacing and respecting type ratios. It is highly configurable and supports custom type fields, type orderings, and different balancing strategies.
 
 ## Method Signature
 
 ```ruby
-TypeBalancer.balance(items, type_field: :type, type_order: nil)
+TypeBalancer.balance(items, type_field: :type, type_order: nil, strategy: nil, **strategy_options)
 ```
 
 ### Arguments
 - `items` (Array<Hash>): The collection of items to balance. Each item should have a type field (default: `:type`).
 - `type_field` (Symbol/String, optional): The key to use for extracting the type from each item. Default is `:type`.
 - `type_order` (Array<String>, optional): An array specifying the desired order of types in the output. If omitted, the gem determines the order automatically.
+- `strategy` (Symbol, optional): The balancing strategy to use. Default is `:sliding_window`.
+- `strategy_options` (Hash, optional): Additional options specific to the chosen strategy.
 
-## Return Value
-- Returns a new array of items, balanced by type and spaced as evenly as possible.
-- The output array will have the same length as the input.
+## Available Strategies
+
+### 1. Sliding Window Strategy (default)
+The sliding window strategy is a sophisticated approach that balances items by examining fixed-size windows of items sequentially. For each window, it:
+1. Calculates the target ratio of each type based on the overall collection
+2. Ensures minimum representation of each type when possible
+3. Distributes remaining slots to maintain target ratios
+4. Handles transitions between windows to maintain smooth distribution
+
+**Technical Details:**
+- Default window size: 10 items
+- Minimum representation: Each type gets at least one slot in a window if ratio > 0
+- Ratio preservation: Maintains approximate global ratios while ensuring local diversity
+- Adaptive sizing: Window size automatically adjusts near the end of the collection
+
+**Configuration Options:**
+```ruby
+TypeBalancer.balance(items,
+  strategy: :sliding_window,
+  window_size: 25,        # Size of the sliding window
+  type_field: :type,      # Field containing type information
+  type_order: %w[...]     # Optional: preferred type order
+)
+```
+
+**When to Use:**
+1. **Content Feed Optimization**
+   - Perfect for social media feeds, blog lists, or any paginated content
+   - Ensures users see a diverse mix regardless of where they stop scrolling
+   ```ruby
+   TypeBalancer.balance(posts, 
+     strategy: :sliding_window,
+     window_size: 10
+   )
+   ```
+
+2. **E-commerce Category Display**
+   - Balances product types in search results or category pages
+   - Maintains category ratios while ensuring variety
+   ```ruby
+   TypeBalancer.balance(products,
+     strategy: :sliding_window,
+     window_size: 15,
+     type_field: :category
+   )
+   ```
+
+3. **News Feed Management**
+   - Mixes different news categories while maintaining importance
+   - Larger windows allow for some natural clustering
+   ```ruby
+   TypeBalancer.balance(articles,
+     strategy: :sliding_window,
+     window_size: 25,
+     type_order: %w[breaking featured regular]
+   )
+   ```
+
+**Window Size Guidelines:**
+- **Small (5-10 items)**
+  - Strictest local balance
+  - Best for: Short lists, critical diversity needs
+  - Example: Featured content sections
+
+- **Medium (15-25 items)**
+  - Balanced local/global distribution
+  - Best for: Standard content feeds
+  - Example: Blog post listings
+
+- **Large (30+ items)**
+  - More gradual transitions
+  - Best for: Long-form content, natural grouping
+  - Example: Search results with category clustering
+
+**Implementation Notes:**
+- The strategy maintains a queue for each type
+- Window calculations consider both used and available items
+- Edge cases (end of collection, single type) are handled gracefully
+- Performance scales linearly with collection size
+
+**Example with Analysis:**
+```ruby
+# Balance a feed with analytics
+items = [
+  { type: 'video', id: 1 },
+  { type: 'article', id: 2 },
+  # ... more items
+]
+
+balanced = TypeBalancer.balance(items,
+  strategy: :sliding_window,
+  window_size: 15,
+  type_field: :type
+)
+
+# Analyze distribution in first window
+first_window = balanced.first(15)
+distribution = first_window.group_by { |i| i[:type] }
+                         .transform_values(&:count)
+```
 
 ## Usage Examples
 
-### 1. Basic Balancing
+### 1. Basic Balancing (Default Strategy)
 ```ruby
 items = [
   { type: 'video', title: 'Video 1' },
@@ -33,11 +132,14 @@ balanced = TypeBalancer.balance(items)
 # => [ { type: 'article', ... }, { type: 'image', ... }, { type: 'video', ... }, ... ]
 ```
 
-### 2. Custom Type Order
+### 2. Custom Strategy Options
 ```ruby
-# Prioritize images, then videos, then articles
-balanced = TypeBalancer.balance(items, type_order: %w[image video article])
-# => [ { type: 'image', ... }, { type: 'video', ... }, { type: 'article', ... }, ... ]
+# Large window size for more gradual transitions
+balanced = TypeBalancer.balance(items,
+  strategy: :sliding_window,
+  window_size: 50,
+  type_order: %w[image video article]
+)
 ```
 
 ### 3. Custom Type Field
@@ -64,6 +166,7 @@ If a type in `type_order` is not present in the input, it is simply ignored in t
 - The `type_order` argument must be an array of strings matching the type values in your items.
 - If you use a custom `type_field`, ensure all items have that field.
 - The method does not mutate the input array.
+- Strategy options are specific to each strategy and are ignored by other strategies.
 
 ## See Also
 - [README.md](../README.md) for general usage

data/docs/quality.md

@@ -53,15 +53,23 @@ The script tests several key aspects of the TypeBalancer gem:
 - Shows spacing calculations between positions
 - Verifies edge cases (single item, no items, all items)
 
-### 2. Robust Balance Method Tests
+### 2. Strategy System
+- Tests the default sliding window strategy
+- Verifies behavior with different window sizes
+- Checks strategy options and customization
+- Ensures backward compatibility with existing code
+
+### 3. Robust Balance Method Tests
 - Loads scenarios from a YAML file (`examples/balance_test_data.yml`)
 - Tests `TypeBalancer.balance` with and without the `type_order` argument
+- Tests different strategy configurations
 - Checks type counts, custom order, and exception handling for empty input
 - Prints a color-coded summary table for pass/fail counts
 
-### 3. Content Feed Example
+### 4. Content Feed Example
 - Shows a real-world example of content type distribution
 - Verifies position allocation for different content types (video, image, article)
+- Tests strategy behavior with real-world data
 - Checks distribution statistics and ratios
 
 ## Output Format

data/examples/large_scale_balance_test.rb

@@ -0,0 +1,168 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# rubocop:disable Metrics/ClassLength
+# rubocop:disable Metrics/MethodLength
+# rubocop:disable Metrics/AbcSize
+
+require_relative '../lib/type_balancer'
+require 'yaml'
+require 'json'
+
+class LargeScaleBalanceTest
+  GREEN = "\e[32m"
+  RED = "\e[31m"
+  YELLOW = "\e[33m"
+  RESET = "\e[0m"
+
+  def initialize
+    @total_records = 500
+    @type_distribution = {
+      'type_a' => 250, # 50%
+      'type_b' => 175, # 35%
+      'type_c' => 75   # 15%
+    }
+    @window_sizes = [10, 25, 50, 100]
+    @failures = []
+    @tests_run = 0
+    @tests_passed = 0
+  end
+
+  def run
+    puts "\n#{YELLOW}Running Large Scale Balance Test#{RESET}"
+    puts "Total Records: #{@total_records}"
+    puts 'Distribution:'
+    @type_distribution.each do |type, count|
+      puts "  #{type}: #{count} (#{(count.to_f / @total_records * 100).round(1)}%)"
+    end
+
+    test_data = generate_test_data
+
+    # Test default strategy
+    puts "\n#{YELLOW}Testing Default Strategy (Sliding Window)#{RESET}"
+    run_balance_test(test_data)
+
+    # Test with different window sizes
+    @window_sizes.each do |size|
+      puts "\n#{YELLOW}Testing Sliding Window Strategy with Window Size #{size}#{RESET}"
+      run_balance_test(test_data, strategy: :sliding_window, window_size: size)
+    end
+
+    # Test with custom type order
+    puts "\n#{YELLOW}Testing with Custom Type Order#{RESET}"
+    run_balance_test(
+      test_data,
+      strategy: :sliding_window,
+      types: %w[type_c type_b type_a],
+      window_size: 25
+    )
+
+    print_summary
+    @failures.empty?
+  end
+
+  private
+
+  def record_failure(message)
+    @failures << message
+  end
+
+  def generate_test_data
+    items = []
+    @type_distribution.each do |type, count|
+      count.times do |i|
+        items << { type: type, id: "#{type}_#{i + 1}" }
+      end
+    end
+    items.shuffle
+  end
+
+  def run_balance_test(test_data, **options)
+    @tests_run += 1
+    puts "\nRunning balance test..."
+
+    begin
+      result = TypeBalancer.balance(test_data, type_field: :type, **options)
+      analyze_result(result, options)
+      @tests_passed += 1
+    rescue StandardError => e
+      record_failure("Balance test failed: #{e.message}")
+      puts "#{RED}Balance test failed: #{e.message}#{RESET}"
+    end
+  end
+
+  def analyze_result(result, options)
+    window_size = options[:window_size] || 10
+    puts "\nAnalyzing windows of size #{window_size}:"
+
+    result.each_slice(window_size).with_index(1) do |window, index|
+      analyze_window(window, index)
+    end
+
+    analyze_overall_distribution(result)
+  end
+
+  def analyze_window(window, window_number)
+    puts "\nAnalyzing window #{window_number} (#{window.size} items):"
+    type_counts = window.group_by { |item| item[:type] }.transform_values(&:size)
+    total_in_window = window.size.to_f
+
+    type_counts.each do |type, count|
+      percentage = (count / total_in_window * 100).round(1)
+      target_percentage = (@type_distribution[type].to_f / @total_records * 100).round(1)
+      diff = (percentage - target_percentage).abs.round(1)
+
+      message = "#{type}: #{count} (#{percentage}%), "
+      message += if diff <= 15
+                   "#{GREEN}acceptable deviation#{RESET}"
+                 else
+                   "#{RED}high deviation#{RESET}"
+                 end
+
+      puts message
+    end
+  end
+
+  def analyze_overall_distribution(result)
+    puts "\nOverall Distribution:"
+    type_counts = result.group_by { |item| item[:type] }.transform_values(&:size)
+    total = result.size.to_f
+
+    type_counts.each do |type, count|
+      percentage = (count / total * 100).round(1)
+      target_percentage = (@type_distribution[type].to_f / @total_records * 100).round(1)
+      diff = (percentage - target_percentage).abs.round(1)
+
+      message = "#{type}: #{count} (#{percentage}% vs target #{target_percentage}%), "
+      message += if diff <= 5
+                   "#{GREEN}good distribution#{RESET}"
+                 else
+                   "#{RED}distribution needs improvement#{RESET}"
+                 end
+
+      puts message
+    end
+  end
+
+  def print_summary
+    puts "\n#{YELLOW}Test Summary:#{RESET}"
+    puts "Tests Run: #{@tests_run}"
+    puts "Tests Passed: #{@tests_passed}"
+    puts "Failures: #{@failures.size}"
+
+    if @failures.any?
+      puts "\n#{RED}Failures:#{RESET}"
+      @failures.each { |failure| puts "- #{failure}" }
+    else
+      puts "\n#{GREEN}All tests passed!#{RESET}"
+    end
+  end
+end
+
+# Run the test
+test = LargeScaleBalanceTest.new
+exit(test.run ? 0 : 1)
+
+# rubocop:enable Metrics/ClassLength
+# rubocop:enable Metrics/MethodLength
+# rubocop:enable Metrics/AbcSize

data/examples/quality.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require 'type_balancer'
+require_relative '../lib/type_balancer'
 require 'yaml'
 
 class QualityChecker
@@ -24,6 +24,7 @@ class QualityChecker
     check_balance_method_robust
     check_real_world_feed
     check_custom_type_field
+    check_strategy_system
 
     print_summary
     exit(@issues.empty? ? 0 : 1)
@@ -351,21 +352,93 @@ class QualityChecker
     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:'
+    puts "\n#{'-' * 80}"
+    puts "#{YELLOW}QUALITY CHECK SUMMARY#{RESET}"
+    puts "#{'-' * 80}"
     puts "Examples Run: #{@examples_run}"
-    puts "Expectations Passed: #{@examples_passed}"
+    puts "Examples Passed: #{@examples_passed}"
+    puts "Examples Failed: #{@examples_run - @examples_passed}"
+    puts "#{'-' * 80}"
 
     if @issues.empty?
-      puts "\n#{GREEN}All quality checks passed! ✓#{RESET}"
+      puts "\n#{GREEN}✓ FINAL STATUS: ALL QUALITY CHECKS PASSED!#{RESET}"
     else
-      puts "\n#{RED}Quality check failed with #{@issues.size} issues:#{RESET}"
+      puts "\n#{RED}✗ FINAL STATUS: QUALITY CHECKS FAILED WITH #{@issues.size} ISSUES:#{RESET}"
       @issues.each_with_index do |issue, index|
         puts "#{RED}#{index + 1}. #{issue}#{RESET}"
       end
     end
-    puts "#{'-' * 50}"
+    puts "#{'-' * 80}"
   end
 
   # Print a summary table for a section

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,52 @@ module TypeBalancer
   class Calculator
     DEFAULT_TYPE_ORDER = %w[video image strip article].freeze
 
-    def initialize(items, type_field: :type, types: nil)
+    # rubocop:disable Metrics/ParameterLists
+    def initialize(items, type_field: :type, types: nil, type_order: 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
+      @type_order = type_order
+      @strategy_name = strategy
+      @strategy_options = strategy_options
     end
+    # rubocop:enable Metrics/ParameterLists
 
     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 with all options
+      strategy = StrategyFactory.create(
+        @strategy_name,
+        items: @items,
+        type_field: @type_field,
+        types: @types || extract_types,
+        type_order: @type_order,
+        **@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
+      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
-        # 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
+        DEFAULT_TYPE_ORDER.select { |type| types.include?(type) } + (types - DEFAULT_TYPE_ORDER)
       end
     end
   end
 end
+
+# Register default strategy
+TypeBalancer::StrategyFactory.register(:sliding_window, TypeBalancer::Strategies::SlidingWindowStrategy)

data/lib/type_balancer/configuration.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module TypeBalancer
+  # Configuration class to handle all balancing options
+  class Configuration
+    attr_accessor :type_field, :type_order, :strategy, :window_size, :batch_size, :types
+    attr_reader :strategy_options
+
+    def initialize(options = {})
+      @type_field = options.fetch(:type_field, :type)
+      @type_order = options[:type_order]
+      @strategy = options[:strategy]
+      @window_size = options[:window_size]
+      @batch_size = options[:batch_size]
+      @types = options[:types]
+      @strategy_options = extract_strategy_options(options)
+    end
+
+    def merge_window_size
+      return strategy_options unless window_size
+
+      strategy_options.merge(window_size: window_size)
+    end
+
+    private
+
+    def extract_strategy_options(options)
+      options.reject { |key, _| %i[type_field type_order strategy window_size types].include?(key) }
+    end
+  end
+end