type_balancer 0.1.0

data/sig/type_balancer.rbs

@@ -0,0 +1,85 @@
+module TypeBalancer
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+
+  class Error < StandardError
+  end
+
+  class ConfigurationError < Error
+  end
+
+  class ValidationError < Error
+  end
+
+  # Main class responsible for balancing items in a collection based on their types
+  class Balancer
+    def initialize: (Array[untyped] collection, ?type_field: Symbol | String, ?types: Array[String]?) -> void
+    def call: -> Array[untyped]
+
+    private
+    def calculate_ratios: (Hash[String, Array[untyped]] items_by_type) -> Array[Float]
+    def get_type: (untyped item) -> String
+    def extract_types: -> Array[String]
+  end
+
+  module Ruby
+    class Calculator
+      def self.calculate_positions: (total_count: Integer, ratio: Float, ?available_items: Array[Integer]?) -> Array[Integer]
+
+      private
+      def self.validate_inputs: (Integer total_count, Float ratio) -> void
+      def self.validate_available_items: (Array[Integer]? available_items, Integer total_count) -> void
+      def self.calculate_positions_without_available: (Integer total_count, Integer target_count) -> Array[Integer]
+      def self.calculate_positions_with_available: (Integer total_count, Integer target_count, Array[Integer] available_items) -> Array[Integer]
+    end
+
+    class BatchCalculator
+      class PositionBatch
+        attr_reader total_count: Integer
+        attr_reader available_count: Integer
+        attr_reader ratio: Float
+
+        def initialize: (total_count: Integer, available_count: Integer, ratio: Float) -> void
+        def valid?: -> bool
+      end
+
+      def self.calculate_positions_batch: (PositionBatch batch, ?Integer iterations) -> Array[Integer]
+      private
+      def self.calculate_target_count: (PositionBatch batch) -> Integer
+    end
+  end
+
+  class OrderedCollectionManager
+    def initialize: (Integer size) -> void
+    def place_at_positions: (Array[untyped] items, Array[Integer] positions) -> void
+    def fill_gaps_alternating: (Array[untyped] primary_items, Array[untyped] secondary_items) -> void
+    def fill_remaining_gaps: (Array[Array[untyped]] items_arrays) -> void
+    def result: -> Array[untyped]
+    private
+    def find_empty_positions: -> Array[Integer]
+  end
+
+  class SequentialFiller
+    def initialize: (Array[untyped] collection, Array[Array[untyped]] items_arrays) -> void
+    def self.fill: (Array[untyped] collection, Array[Integer] positions, Array[Array[untyped]] items_arrays) -> void
+    def fill_gaps: (Array[Integer] positions) -> void
+  end
+
+  class AlternatingFiller
+    def initialize: (Array[untyped] collection, Array[untyped] primary_items, Array[untyped] secondary_items) -> void
+    def self.fill: (Array[untyped] collection, Array[Integer] positions, Array[untyped] primary_items, Array[untyped] secondary_items) -> void
+    def fill_gaps: (Array[Integer] positions) -> void
+  end
+
+  class DistributionCalculator
+    def initialize: (?Float target_ratio) -> void
+    def calculate_target_positions: (Integer total_count, Integer available_items_count, ?Float target_ratio) -> Array[Integer]
+  end
+
+  module Distributor
+    def self.calculate_target_positions: (Integer total_count, Integer available_count, Float ratio) -> Array[Integer]
+  end
+
+  def self.balance: (Array[untyped] collection, ?type_field: Symbol | String, ?type_order: Array[String]?) -> Array[untyped]
+  def self.extract_types: (Array[untyped] collection, Symbol | String type_field) -> Array[String]
+end

data/type_balancer.gemspec

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require_relative 'lib/type_balancer/version'
+
+Gem::Specification.new do |spec|
+  spec.name = 'type_balancer'
+  spec.version = TypeBalancer::VERSION
+  spec.authors = ['Carl Smith']
+  spec.email = ['carl@llweb.biz']
+
+  spec.summary = 'Balances types in collections'
+  spec.description = 'Balances types in collections by ensuring each type appears a similar number of times'
+  spec.homepage = 'https://github.com/llwebconsulting/type_balancer'
+  spec.license = 'MIT'
+  spec.required_ruby_version = '>= 3.2.0'
+
+  spec.metadata['homepage_uri'] = spec.homepage
+  spec.metadata['source_code_uri'] = 'https://github.com/llwebconsulting/type_balancer'
+  spec.metadata['changelog_uri'] = 'https://github.com/llwebconsulting/type_balancer/blob/main/CHANGELOG.md'
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (File.expand_path(f) == __FILE__) || f.start_with?(*%w[bin/ test/ spec/ features/ .git .circleci appveyor ext/
+                                                             c_tests/])
+    end
+  end
+  spec.bindir = 'exe'
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+  spec.metadata['rubygems_mfa_required'] = 'true'
+end

metadata

@@ -0,0 +1,77 @@
+--- !ruby/object:Gem::Specification
+name: type_balancer
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Carl Smith
+bindir: exe
+cert_chain: []
+date: 2025-04-10 00:00:00.000000000 Z
+dependencies: []
+description: Balances types in collections by ensuring each type appears a similar
+  number of times
+email:
+- carl@llweb.biz
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rubocop.yml"
+- ".ruby-version"
+- CHANGELOG.md
+- Dockerfile
+- Gemfile
+- Gemfile.lock
+- LICENSE.txt
+- README.md
+- Rakefile
+- benchmark/README.md
+- benchmark/end_to_end_benchmark.rb
+- benchmark/quick_benchmark.rb
+- benchmark_output.log
+- benchmark_results/ruby3.2.8.txt
+- benchmark_results/ruby3.2.8_yjit.txt
+- benchmark_results/ruby3.3.7.txt
+- benchmark_results/ruby3.3.7_yjit.txt
+- benchmark_results/ruby3.4.2.txt
+- benchmark_results/ruby3.4.2_yjit.txt
+- docs/benchmarks/README.md
+- examples/quality.rb
+- lib/type_balancer.rb
+- lib/type_balancer/alternating_filler.rb
+- lib/type_balancer/balancer.rb
+- lib/type_balancer/calculator.rb
+- lib/type_balancer/distribution_calculator.rb
+- lib/type_balancer/distributor.rb
+- lib/type_balancer/ordered_collection_manager.rb
+- lib/type_balancer/sequential_filler.rb
+- lib/type_balancer/version.rb
+- sig/type_balancer.rbs
+- type_balancer.gemspec
+homepage: https://github.com/llwebconsulting/type_balancer
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/llwebconsulting/type_balancer
+  source_code_uri: https://github.com/llwebconsulting/type_balancer
+  changelog_uri: https://github.com/llwebconsulting/type_balancer/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.2
+specification_version: 4
+summary: Balances types in collections
+test_files: []