type_balancer 0.1.2 → 0.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8ffc72598d68e02ede3d667d51d4eb3bafd48597cddbb36e124cdb95a8e6f54c
-  data.tar.gz: fd4d236432a8490e20271c66235ecd4bcd114cb6d5ceb213dbbc7e9346f7037e
+  metadata.gz: 6c93fa5dcb75821b9f9ea3340f06ca63d67f84781bcf90f13ac089abac7283b7
+  data.tar.gz: fbfadcf9eed52f9f82a5f0a99f05fe3801c8529c32735f3d2eac5b0d42648a4b
 SHA512:
-  metadata.gz: ea6b99ba44cb6e209a122a18a16a88cc8a8ccb6c5f8a1ceba1a443344489e1744cc3d105886d27df4e601a2149d0bbf0a72cabc9ddd5f766a3fada1d88abc64e
-  data.tar.gz: eac933d9f6b1e77f4ec4e83794aabd09dabd47f4a83fd10e148e40680c0cff411dd33c8eaf343823b830206c7b16536c954372788e78bcd65cecbbac5d09d227
+  metadata.gz: 316f4c79fb96b3ff7362a61a4524f2d08e67be712b23f6c1a6f36d4b24332ae58266ce2fbd6dd39a7deea190f9f2f9e965c0bafe94443dd24be571ed62f302fd
+  data.tar.gz: 054a3439add0798dc20593ace1681734fbed87f4d162baeb9e41b6f672cbbb43c7c2b17cd67a92d2c1a4a047b9418707139c2168cdcbde08a105376af53eb39e

data/CHANGELOG.md

@@ -1,11 +1,23 @@
 # Changelog
 
-## [0.1.2] - 2024-04-11
+## [0.1.4] - 2025-04-29
+
+### Fixed
+- Fixed issue with providing a custom type field
+
+## [0.1.3] - 2025-04-27
+
+### Fixed
+- Fixed type balancing behavior to properly handle edge cases where type ratios need to be maintained while respecting original collection order
+- Enhanced position calculation to ensure consistent type distribution across the balanced collection
+- Improved test coverage to verify correct type ratio preservation
+
+## [0.1.2] - 2025-04-11
 
 - Re-release of 0.1.1 due to RubyGems.org publishing issue
 - No functional changes from 0.1.1
 
-## [0.1.1] - 2024-03-XX
+## [0.1.1] - 2025-04-10
 
 ### Refactoring
 - Major refactoring of core components to follow SOLID principles:

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    type_balancer (0.1.2)
+    type_balancer (0.1.4)
 
 GEM
   remote: https://rubygems.org/

data/README.md

@@ -20,7 +20,7 @@ TypeBalancer is a sophisticated Ruby gem designed to solve the challenge of dist
 
 The gem uses advanced distribution algorithms to ensure that items are not only balanced by type but also maintain optimal spacing, preventing clusters of similar content while respecting specified ratios.
 
-[View Examples & Quality Tests](docs/quality.md) | [View Benchmark Results](docs/benchmarks/README.md)
+[View Documentation](docs/README.md) | [View Benchmark Results](docs/benchmarks/README.md)
 
 ## Installation
 
@@ -56,6 +56,60 @@ items = [
 balanced_items = TypeBalancer.balance(items, type_field: :type)
 ```
 
+## Balancing Collections with `TypeBalancer.balance`
+
+The primary method for balancing collections is `TypeBalancer.balance`. This method takes an array of items and distributes them by type, ensuring optimal spacing and respecting type ratios.
+
+**Basic Example:**
+
+```ruby
+items = [
+  { type: 'video', title: 'Video 1' },
+  { type: 'image', title: 'Image 1' },
+  { type: 'article', title: 'Article 1' },
+  # ...
+]
+balanced = TypeBalancer.balance(items, type_field: :type)
+# => [ { type: 'article', ... }, { type: 'image', ... }, { type: 'video', ... }, ... ]
+```
+
+**Custom Type Order:**
+
+You can specify a custom order for types using the `type_order` argument. This controls the priority of types in the balanced output.
+
+```ruby
+# Prioritize images, then videos, then articles
+balanced = TypeBalancer.balance(items, type_field: :type, type_order: %w[image video article])
+# => [ { type: 'image', ... }, { type: 'video', ... }, { type: 'article', ... }, ... ]
+```
+
+- `type_field`: The key to use for type extraction (default: `:type`).
+- `type_order`: An array of type names (as strings) specifying the desired order.
+
+For more advanced usage and options, see [Detailed Balance Method Documentation](docs/balance.md).
+
+## Calculating Positions Directly
+
+In addition to balancing collections, you can use `TypeBalancer.calculate_positions` to determine optimal positions for a given type or subset of items within a sequence. This is useful for advanced scenarios where you need fine-grained control over item placement.
+
+**Basic Example:**
+
+```ruby
+# Calculate positions for 3 items in a sequence of 10 slots
+positions = TypeBalancer.calculate_positions(total_count: 10, ratio: 0.3)
+# => [0, 5, 9]
+```
+
+**With Available Items:**
+
+```ruby
+# Restrict placement to specific slots
+positions = TypeBalancer.calculate_positions(total_count: 10, ratio: 0.5, available_items: [0, 1, 2])
+# => [0, 1, 2]
+```
+
+For more advanced usage and options, see [Detailed Position Calculation Documentation](docs/calculate_positions.md).
+
 ## Performance Characteristics
 
 TypeBalancer is designed to handle collections of varying sizes efficiently. Here are the current performance metrics:
@@ -91,7 +145,7 @@ After checking out the repo, run `bin/setup` to install dependencies. Then:
 3. Run `rake rubocop` to check code style
 4. Run `bin/console` for an interactive prompt
 
-For more information about the quality script and its uses, see our [quality script documentation](docs/quality.md).
+For more information about the gem, its features, and quality checks, see our [documentation](docs/README.md).
 
 ## Contributing
 
@@ -140,7 +194,7 @@ We welcome contributions to TypeBalancer! Here's how you can help:
 - Quality script should pass without new issues
 
 For more detailed information about our development process and tools:
-- [Quality Script Documentation](docs/quality.md)
+- [Documentation](docs/README.md)
 - [Benchmark Documentation](docs/benchmarks/README.md)
 
 ## License

data/docs/README.md

@@ -0,0 +1,8 @@
+# Documentation Index
+
+Welcome to the TypeBalancer documentation! Below you'll find links to all major documentation resources for the gem.
+
+- [Quality Script](quality.md): Integration and example script for verifying gem functionality, with instructions for running locally or from other projects.
+- [Balance Method Details](balance.md): In-depth documentation for the `TypeBalancer.balance` method, including arguments, usage, and edge cases.
+- [Calculate Positions Method Details](calculate_positions.md): Detailed documentation for `TypeBalancer.calculate_positions`, with examples and caveats.
+- [Benchmarks](benchmarks/README.md): Performance metrics and benchmarking methodology for the gem. 

data/docs/balance.md

@@ -0,0 +1,71 @@
+# 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.
+
+## Method Signature
+
+```ruby
+TypeBalancer.balance(items, type_field: :type, type_order: nil)
+```
+
+### 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.
+
+## 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.
+
+## Usage Examples
+
+### 1. Basic Balancing
+```ruby
+items = [
+  { type: 'video', title: 'Video 1' },
+  { type: 'image', title: 'Image 1' },
+  { type: 'article', title: 'Article 1' },
+  { type: 'article', title: 'Article 2' },
+  { type: 'image', title: 'Image 2' },
+  { type: 'video', title: 'Video 2' }
+]
+balanced = TypeBalancer.balance(items)
+# => [ { type: 'article', ... }, { type: 'image', ... }, { type: 'video', ... }, ... ]
+```
+
+### 2. Custom Type Order
+```ruby
+# Prioritize images, then videos, then articles
+balanced = TypeBalancer.balance(items, type_order: %w[image video article])
+# => [ { type: 'image', ... }, { type: 'video', ... }, { type: 'article', ... }, ... ]
+```
+
+### 3. Custom Type Field
+```ruby
+items = [
+  { category: 'video', title: 'Video 1' },
+  { category: 'image', title: 'Image 1' },
+  { category: 'article', title: 'Article 1' }
+]
+balanced = TypeBalancer.balance(items, type_field: :category)
+# => [ { category: 'article', ... }, { category: 'image', ... }, { category: 'video', ... } ]
+```
+
+### 4. Handling Missing Types
+If a type in `type_order` is not present in the input, it is simply ignored in the output order.
+
+### 5. Edge Cases
+- **Empty Input:** Raises an exception (`Collection cannot be empty`).
+- **Single Type:** All items are returned in their original order.
+- **Missing Type Field:** If an item is missing the type field, it is ignored or may cause an error depending on context.
+
+## Notes and Caveats
+- The method is deterministic: the same input will always produce the same output.
+- 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.
+
+## See Also
+- [README.md](../README.md) for general usage
+- [Quality Script Documentation](quality.md) for integration tests and examples
+- [Detailed Position Calculation Documentation](calculate_positions.md) 

data/docs/calculate_positions.md

@@ -0,0 +1,87 @@
+# Detailed Documentation: `TypeBalancer.calculate_positions`
+
+`TypeBalancer.calculate_positions` is a utility method for determining the optimal positions for a given number of items (or a ratio of items) within a sequence of slots. This is useful for advanced scenarios where you want to control the distribution of a specific type or subset of items.
+
+## Method Signature
+
+```ruby
+TypeBalancer.calculate_positions(total_count:, ratio:, available_items: nil)
+```
+
+### Arguments
+- `total_count` (Integer): The total number of slots in the sequence (e.g., the length of your feed or array).
+- `ratio` (Float): The desired ratio of items to place (e.g., `0.3` for 30%).
+- `available_items` (Array<Integer>, optional): An array of slot indices where placement is allowed. If omitted, all slots are considered available.
+
+## Return Value
+- Returns an array of integer indices representing the optimal positions for the items.
+- The array will have a length close to `total_count * ratio`, rounded as appropriate.
+- If `available_items` is provided, only those slots will be used.
+
+## Usage Examples
+
+### 1. Even Distribution
+```ruby
+# Place 3 items evenly in 10 slots
+TypeBalancer.calculate_positions(total_count: 10, ratio: 0.3)
+# => [0, 5, 9]
+```
+
+### 2. Restricting to Available Slots
+```ruby
+# Only use slots 0, 1, and 2
+TypeBalancer.calculate_positions(total_count: 10, ratio: 0.5, available_items: [0, 1, 2])
+# => [0, 1, 2]
+```
+
+### 3. Edge Cases
+```ruby
+# Single item
+TypeBalancer.calculate_positions(total_count: 1, ratio: 1.0)
+# => [0]
+
+# No items
+TypeBalancer.calculate_positions(total_count: 100, ratio: 0.0)
+# => []
+
+# All items
+TypeBalancer.calculate_positions(total_count: 5, ratio: 1.0)
+# => [0, 1, 2, 3, 4]
+```
+
+### 4. Precision with Small Ratios
+```ruby
+# Two positions in three slots
+TypeBalancer.calculate_positions(total_count: 3, ratio: 0.67)
+# => [0, 1]
+
+# Single position in three slots
+TypeBalancer.calculate_positions(total_count: 3, ratio: 0.34)
+# => [0]
+```
+
+### 5. Available Items Edge Cases
+```ruby
+# Single target with multiple available positions
+TypeBalancer.calculate_positions(total_count: 5, ratio: 0.2, available_items: [1, 2, 3])
+# => [1]
+
+# Two targets with multiple available positions
+TypeBalancer.calculate_positions(total_count: 10, ratio: 0.2, available_items: [1, 3, 5])
+# => [1, 5]
+
+# Exact match of available positions
+TypeBalancer.calculate_positions(total_count: 10, ratio: 0.3, available_items: [2, 4, 6])
+# => [2, 4, 6]
+```
+
+## Notes and Caveats
+- If `ratio` is 0 or `total_count` is 0, returns an empty array.
+- If `ratio` is 1.0, returns all available slots.
+- If `available_items` is provided and its length is less than the target count, all available items are returned.
+- For very small or very large ratios, the method ensures at least one or all slots are used, respectively.
+- The method is deterministic and will always return the same result for the same input.
+
+## See Also
+- [README.md](../README.md) for general usage
+- [Quality Script Documentation](quality.md) for integration tests and examples 

data/docs/quality.md

@@ -8,12 +8,42 @@ The TypeBalancer gem includes a comprehensive quality check script located at `/
 
 ## Running the Script
 
-To run the quality script:
+To run the quality script from the gem repository:
 
 ```bash
 bundle exec ruby examples/quality.rb
 ```
 
+### Running from Other Projects
+
+You can run the quality script from any project that includes the TypeBalancer gem. This is useful for verifying the gem's behavior in your app or as part of CI for downstream projects.
+
+**Example:**
+
+```bash
+bundle exec ruby /path/to/gems/type_balancer/examples/quality.rb
+```
+
+**How do I find the path to the gem?**
+
+If you are not sure where the gem is installed, you can use Bundler to locate it:
+
+```bash
+bundle show type_balancer
+```
+
+This will print the path to the gem directory. The quality script is located in the `examples` subdirectory of that path. For example:
+
+```bash
+$ bundle show type_balancer
+/Users/yourname/.rbenv/versions/3.2.2/lib/ruby/gems/3.2.0/gems/type_balancer-0.1.3
+$ bundle exec ruby /Users/yourname/.rbenv/versions/3.2.2/lib/ruby/gems/3.2.0/gems/type_balancer-0.1.3/examples/quality.rb
+```
+
+- Ensure the gem is installed and available in your bundle.
+- The script expects the test data file at `examples/balance_test_data.yml` (relative to the gem root).
+- Output will be color-coded if your terminal supports ANSI colors.
+
 ## What it Tests
 
 The script tests several key aspects of the TypeBalancer gem:
@@ -23,32 +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. Content Feed Example
+### 2. 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
+- 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
 - Shows a real-world example of content type distribution
 - Verifies position allocation for different content types (video, image, article)
 - Checks distribution statistics and ratios
 
-### 3. Balancer API
-- Tests the main TypeBalancer.balance method
-- Verifies batch creation and size limits
-- Demonstrates custom type ordering
-
-### 4. Type Extraction
-- Tests type extraction from both hash and object items
-- Verifies support for different type field access methods
-
-### 5. Error Handling
-- Validates handling of empty collections
-- Tests response to invalid type fields
-- Verifies batch size validation
-
 ## Output Format
 
-The script provides detailed output showing:
-- Results of each test case
-- Distribution statistics
-- Any issues found during testing
-- A summary of all examples run and passed
+- Each section prints a color-coded summary table of passing and failing tests
+- Failures and exceptions are highlighted in red; passes in green
+- The final summary shows the total number of examples run and passed
+- The script exits with status 0 if all tests pass, or 1 if any fail (CI-friendly)
 
 ## Using as a Development Tool
 
@@ -58,6 +79,19 @@ The quality script is particularly useful when:
 3. Verifying changes haven't broken core functionality
 4. Understanding how different features work together
 
+## Customizing/Extending the Script
+
+- You can add new scenarios to `examples/balance_test_data.yml` to test additional cases or edge conditions.
+- You may copy or extend the script for your own integration tests.
+- The script can be adapted to accept a custom YAML path if needed (see comments in the script).
+
+## Troubleshooting
+
+- **Color output not working:** Ensure your terminal supports ANSI colors.
+- **File not found:** Make sure `examples/balance_test_data.yml` exists and is accessible from the script's location.
+- **Gem not found:** Ensure the TypeBalancer gem is installed and available in your bundle.
+- **Path issues:** Use an absolute or correct relative path to the script when running from another project.
+
 ## Extending the Script
 
 When adding new features to TypeBalancer, consider:

data/examples/balance_test_data.yml

@@ -0,0 +1,66 @@
+# Test data for TypeBalancer.balance integration tests
+
+- name: Even distribution
+  items:
+    - { type: video, id: 1 }
+    - { type: video, id: 2 }
+    - { type: image, id: 3 }
+    - { type: image, id: 4 }
+    - { type: article, id: 5 }
+    - { type: article, id: 6 }
+    - { type: article, id: 7 }
+    - { type: article, id: 8 }
+  expected_type_counts:
+    video: 2
+    image: 2
+    article: 4
+
+- name: Uneven distribution
+  items:
+    - { type: video, id: 1 }
+    - { type: image, id: 2 }
+    - { type: article, id: 3 }
+    - { type: article, id: 4 }
+    - { type: article, id: 5 }
+    - { type: article, id: 6 }
+    - { type: article, id: 7 }
+    - { type: article, id: 8 }
+  expected_type_counts:
+    video: 1
+    image: 1
+    article: 6
+
+- name: Missing type (no images)
+  items:
+    - { type: video, id: 1 }
+    - { type: video, id: 2 }
+    - { type: article, id: 3 }
+    - { type: article, id: 4 }
+    - { type: article, id: 5 }
+  expected_type_counts:
+    video: 2
+    article: 3
+
+- name: Custom type order
+  items:
+    - { type: video, id: 1 }
+    - { type: image, id: 2 }
+    - { type: article, id: 3 }
+    - { type: article, id: 4 }
+    - { type: image, id: 5 }
+    - { type: video, id: 6 }
+    - { type: article, id: 7 }
+  type_order: [image, video, article]
+  expected_first_type: image
+
+- name: Edge case - empty
+  items: []
+  expected_type_counts: {}
+
+- name: Edge case - single type
+  items:
+    - { type: article, id: 1 }
+    - { type: article, id: 2 }
+    - { type: article, id: 3 }
+  expected_type_counts:
+    article: 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
@@ -15,7 +21,9 @@ class QualityChecker
     check_edge_cases
     check_position_precision
     check_available_positions_edge_cases
+    check_balance_method_robust
     check_real_world_feed
+    check_custom_type_field
 
     print_summary
     exit(@issues.empty? ? 0 : 1)
@@ -29,11 +37,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
@@ -49,6 +61,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,
@@ -58,6 +71,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
@@ -70,33 +84,40 @@ 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_position_precision
@@ -104,23 +125,28 @@ class QualityChecker
     
     # Two positions in three slots
     @examples_run += 1
+    @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
 
     # 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
 
   def check_available_positions_edge_cases
@@ -128,6 +154,7 @@ class QualityChecker
 
     # Single target with multiple available positions
     @examples_run += 1
+    @section_examples_run += 1
     positions = TypeBalancer.calculate_positions(
       total_count: 5,
       ratio: 0.2,
@@ -136,12 +163,14 @@ class QualityChecker
     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
 
     # Two targets with multiple available positions
     @examples_run += 1
+    @section_examples_run += 1
     positions = TypeBalancer.calculate_positions(
       total_count: 10,
       ratio: 0.2,
@@ -150,12 +179,14 @@ class QualityChecker
     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
 
     # Exact match of available positions
     @examples_run += 1
+    @section_examples_run += 1
     positions = TypeBalancer.calculate_positions(
       total_count: 10,
       ratio: 0.3,
@@ -164,17 +195,111 @@ class QualityChecker
     puts "Exact match of available positions: #{positions.inspect}"
     if positions == [2, 4, 6]
       @examples_passed += 1
+      @section_examples_passed += 1
     else
       record_issue("Exact match case returned #{positions.inspect} instead of [2, 4, 6]")
     end
+    print_section_table('calculate_positions')
+  end
+
+  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']
+
+      # 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 "\nReal World Example - Content Feed:"
+    puts "\n#{YELLOW}Real World Example - Content Feed:#{RESET}"
     feed_size = 20
-
-    # Create test items
     items = [
       { type: 'video', id: 1 },
       { type: 'video', id: 2 },
@@ -186,87 +311,44 @@ class QualityChecker
       { type: 'article', id: 8 },
       { type: 'article', id: 9 }
     ]
-
-    # Track allocated positions
-    allocated_positions = []
-    content_positions = {}
-
-    # 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]
-
-    content_positions[:image] = TypeBalancer.calculate_positions(
-      total_count: feed_size,
-      ratio: 0.4,
-      available_items: (0..14).to_a - allocated_positions
-    )
-    allocated_positions += content_positions[:image]
-
-    content_positions[:article] = TypeBalancer.calculate_positions(
-      total_count: feed_size,
-      ratio: 0.3,
-      available_items: (0..19).to_a - allocated_positions
-    )
-
-    puts "\nContent Type Positions:"
-    content_positions.each do |type, pos|
-      puts "#{type}: #{pos.inspect}"
-    end
-
-    # Check for overlaps
-    all_positions = content_positions.values.compact.flatten
-    if all_positions == all_positions.uniq
-      puts "\nSuccess: No overlapping positions!"
-      @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!"
-    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)"
-
-      if count != expected_counts[type]
-        record_issue("#{type} count #{count} doesn't match expected #{expected_counts[type]}")
-      end
-    end
-
     # Test with custom type order
     ordered_result = TypeBalancer.balance(
       items,
       type_field: :type,
       type_order: %w[article image video]
     )
-
-    # Verify type order is respected
     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")
+      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
 
-    # Test position calculation
-    positions = TypeBalancer::Distributor.calculate_target_positions(
-      total_count: 10,
-      ratio: 0.3
-    )
-    if positions.is_a?(Array) && positions.all? { |p| p.is_a?(Integer) }
+  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("Position calculation failed")
+      record_issue("Expected #{expected.inspect}, got #{found.inspect}")
+      puts "#{RED}Custom field test failed: #{found.inspect}#{RESET}"
     end
-
-    puts "\nBalanced items with custom order:"
+    print_section_table('custom_type_field', 1, found == expected ? 1 : 0)
   end
 
   def print_summary
@@ -276,15 +358,28 @@ class QualityChecker
     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

@@ -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/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

data/lib/type_balancer/type_extractor_registry.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module TypeBalancer
+  # Registry to memoize TypeExtractor per type_field in thread/request scope
+  class TypeExtractorRegistry
+    STORAGE_KEY = :type_balancer_extractors
+
+    def self.get(type_field)
+      cache[type_field] ||= TypeExtractor.new(type_field)
+    end
+
+    def self.clear!
+      Thread.current[STORAGE_KEY] = nil
+    end
+
+    def self.cache
+      Thread.current[STORAGE_KEY] ||= {}
+    end
+  end
+end

data/lib/type_balancer/version.rb

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

data/lib/type_balancer.rb

@@ -6,6 +6,8 @@ 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/type_extractor'
+require_relative 'type_balancer/type_extractor_registry'
 
 module TypeBalancer
   class Error < StandardError; end
@@ -33,31 +35,27 @@ module TypeBalancer
     # Input validation
     raise EmptyCollectionError, 'Collection cannot be empty' if items.empty?
 
-    # Extract and validate types
-    types = extract_types(items, type_field)
-    raise Error, "Invalid type field: #{type_field}" if types.empty?
-
-    # Group items by type
-    items.group_by { |item| extract_type(item, type_field) }
+    # Use centralized extractor
+    extractor = TypeExtractorRegistry.get(type_field)
+    begin
+      types = extractor.extract_types(items)
+      raise Error, "Invalid type field: #{type_field}" if types.empty?
+    rescue Error => e
+      raise Error, "Cannot access type field '#{type_field}': #{e.message}"
+    end
 
-    # Initialize balancer with type order if provided
-    balancer = Balancer.new(types, type_order: type_order)
+    # Initialize balancer with type order and type field
+    balancer = Balancer.new(types, type_field: type_field, type_order: type_order)
 
     # Balance items
     balancer.call(items)
   end
 
+  # Backward compatibility methods
   def self.extract_types(items, type_field)
-    items.map { |item| extract_type(item, type_field) }.uniq
-  end
-
-  def self.extract_type(item, type_field)
-    if item.is_a?(Hash)
-      item[type_field] || item[type_field.to_s]
-    else
-      item.public_send(type_field)
-    end
-  rescue NoMethodError
-    nil
+    TypeExtractorRegistry.get(type_field).extract_types(items)
+  rescue Error
+    # For backward compatibility, return array with nil for inaccessible type fields
+    [nil]
   end
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: type_balancer
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.1.4
 platform: ruby
 authors:
 - Carl Smith
 bindir: exe
 cert_chain: []
-date: 1980-01-02 00:00:00.000000000 Z
+date: 2025-04-29 00:00:00.000000000 Z
 dependencies: []
 description: Balances types in collections by ensuring each type appears a similar
   number of times
@@ -37,8 +37,12 @@ files:
 - benchmark_results/ruby3.3.7_yjit.txt
 - benchmark_results/ruby3.4.2.txt
 - benchmark_results/ruby3.4.2_yjit.txt
+- docs/README.md
+- docs/balance.md
 - docs/benchmarks/README.md
+- docs/calculate_positions.md
 - docs/quality.md
+- examples/balance_test_data.yml
 - examples/quality.rb
 - lib/type_balancer.rb
 - lib/type_balancer/alternating_filler.rb
@@ -52,6 +56,7 @@ files:
 - lib/type_balancer/ratio_calculator.rb
 - lib/type_balancer/sequential_filler.rb
 - lib/type_balancer/type_extractor.rb
+- lib/type_balancer/type_extractor_registry.rb
 - lib/type_balancer/version.rb
 - type_balancer.gemspec
 homepage: https://github.com/llwebconsulting/type_balancer
@@ -76,7 +81,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.7
+rubygems_version: 3.6.2
 specification_version: 4
 summary: Balances types in collections
 test_files: []