elo_rankable 0.1.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ef2f0385ffa82f1a5e8b5d225e0e76252685f622f1cfe80f32894d76de088a33
+  data.tar.gz: de145551fe657a328ef79b41e67493a580ee6b1a6b266b775443b231b243173d
+SHA512:
+  metadata.gz: ba1215784c8f619cf9a1094478faa86bc5fb18050e8e5a1b0e790db5d30e8f552416b1719579c5815452945e926e7dc1df8c498e0035f97193c70afa3f2aeb78
+  data.tar.gz: 4ec3e6164342ad4854da73b420bed52fa210e572e9de9b002fda7014f1e239ef30b842e18ce9f545b4313582cc5a8d201ad42ca20b4022722b0ddb96531d17a1

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,35 @@
+AllCops:
+  NewCops: enable
+  SuggestExtensions: false
+  TargetRubyVersion: 2.7
+
+# Disable some overly strict metrics for gem development
+Metrics/AbcSize:
+  Max: 30
+
+Metrics/MethodLength:
+  Max: 15
+
+Metrics/CyclomaticComplexity:
+  Max: 10
+
+Metrics/PerceivedComplexity:
+  Max: 10
+
+Metrics/BlockLength:
+  Exclude:
+    - 'spec/**/*'
+    - '*.gemspec'
+
+# Allow longer variable names with numbers for test clarity
+Naming/VariableNumber:
+  EnforcedStyle: normalcase
+
+# Allow predicate method names like has_elo_ranking for ActiveRecord-style methods
+Naming/PredicatePrefix:
+  AllowedMethods:
+    - has_elo_ranking
+
+# Documentation is not always necessary for internal classes
+Style/Documentation:
+  Enabled: false

data/CHANGELOG.md

@@ -0,0 +1,59 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.2] - 2025-08-08
+
+### Added
+- Comprehensive input validation for all public methods
+- Early validation in `record_multiplayer_match` and `record_winner_vs_all` methods
+- Validation for `record_draw` method
+- Defensive validation in Calculator methods
+- Detection of duplicate players in multiplayer matches
+- Validation for nil values in player arrays
+- Validation for non-rankable objects
+- Validation for destroyed/deleted players
+
+### Fixed
+- **BREAKING**: Improved error handling with descriptive ArgumentError exceptions instead of NoMethodError or database constraint violations
+- Fixed validation gaps where errors would bubble up from Calculator instead of being caught early
+- Fixed race conditions in validation logic by caching `elo_ranking` calls
+- Improved validation in `validate_opponent!` method to properly handle destroyed records
+
+### Changed
+- **BREAKING**: `record_multiplayer_match` now raises `ArgumentError` for duplicate players instead of allowing self-matches
+- **BREAKING**: `record_winner_vs_all` now validates winner and losers arrays upfront
+- **BREAKING**: `record_draw` now validates both players upfront
+- All validation errors now provide clear, descriptive error messages
+
+## [0.1.1] - 2025-08-07
+
+### Fixed
+- Added proper input validation to `beat!`, `lost_to!`, and `draw_with!` methods
+- Fixed SQLite3 gem version compatibility with ActiveRecord 8.0
+
+### Added
+- Comprehensive edge case testing for high ratings, negative ratings, and invalid inputs
+- Performance tests for leaderboard queries and association loading
+- Input validation with descriptive error messages for nil players and self-matches
+
+### Changed
+- Improved error handling with ArgumentError exceptions for invalid match scenarios
+- Enhanced test suite with better coverage of edge cases and error conditions
+
+## [0.1.0] - 2025-08-06
+
+### Added
+- Initial release
+- `has_elo_ranking` macro for ActiveRecord models
+- Support for 1v1 matches with `beat!`, `lost_to!`, and `draw_with!` methods
+- Multiplayer ranked match support via `EloRankable.record_multiplayer_match`
+- Winner-vs-all match support via `EloRankable.record_winner_vs_all`
+- Configurable base rating and K-factor strategies
+- Leaderboard scopes (`by_elo_rating`, `top_rated`)
+- Polymorphic EloRanking model for clean separation
+- Rails generator for database migration
+- Comprehensive test suite

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 EloRankable Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,309 @@
+# elo_rankable
+
+A Ruby gem that adds Elo rating capabilities to any ActiveRecord model using a simple `has_elo_ranking` declaration. It stores ratings in a separate `EloRanking` model to keep your host model clean, and provides domain-style methods for updating rankings after matches.
+
+## Features
+
+- 🎯 **Simple Integration**: Add Elo rankings to any ActiveRecord model with one line
+- 🏆 **Multiple Match Types**: Support for 1v1, draws, multiplayer (ranked), and winner-vs-all matches
+- ⚙️ **Configurable**: Customizable base rating and K-factor strategies
+- 📊 **Leaderboards**: Built-in scopes for rankings and top players
+- 🧹 **Clean Design**: Ratings stored separately from your main models
+- 🔄 **Polymorphic**: Works with any ActiveRecord model (User, Player, Team, etc.)
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'elo_rankable'
+```
+
+And then execute:
+
+```bash
+$ bundle install
+```
+
+Or install it yourself as:
+
+```bash
+$ gem install elo_rankable
+```
+
+## Setup
+
+### 1. Generate and run the migration
+
+```bash
+$ rails generate elo_rankable:install
+$ rails db:migrate
+```
+
+### 2. Add to your models
+
+```ruby
+class Player < ApplicationRecord
+  has_elo_ranking
+end
+
+class Team < ApplicationRecord
+  has_elo_ranking
+end
+```
+
+## Usage
+
+### Basic 1v1 Matches
+
+```ruby
+alice = Player.create!(name: "Alice")
+bob = Player.create!(name: "Bob")
+
+# Both players start with the default rating (1200)
+alice.elo_rating  # => 1200
+bob.elo_rating    # => 1200
+
+# Record a match where Alice beats Bob
+alice.beat!(bob)
+
+alice.elo_rating  # => 1216
+bob.elo_rating    # => 1184
+
+# Alternative syntax
+bob.lost_to!(alice)  # Same effect as alice.beat!(bob)
+
+# Record a draw
+alice.draw_with!(bob)
+
+alice.elo_rating  # => 1200 (no change for equal ratings)
+bob.elo_rating    # => 1200 (no change for equal ratings)
+
+# Example with different ratings
+charlie = Player.create!(name: "Charlie")
+charlie.elo_ranking.update!(rating: 1400)  # Charlie is higher rated
+
+charlie.draw_with!(alice)  # Draw between 1400 vs 1200
+
+charlie.elo_rating  # => 1392 (lost 8 points - draw hurts higher rated player)
+alice.elo_rating    # => 1208 (gained 8 points - draw helps lower rated player)
+```
+
+### Multiplayer Matches (Ranked)
+
+For tournaments or matches where players finish in ranked order:
+
+```ruby
+players = [first_place, second_place, third_place, fourth_place]
+
+# Higher-indexed players are treated as having lost to lower-indexed ones
+EloRankable.record_multiplayer_match(players)
+
+# This is equivalent to:
+# first_place.beat!(second_place)
+# first_place.beat!(third_place)
+# first_place.beat!(fourth_place)
+# second_place.beat!(third_place)
+# second_place.beat!(fourth_place)
+# third_place.beat!(fourth_place)
+```
+
+### Winner vs All Matches
+
+For matches where one player/team beats everyone else, but the losers don't compete against each other:
+
+```ruby
+winner = Player.find_by(name: "Champion")
+losers = [player1, player2, player3]
+
+EloRankable.record_winner_vs_all(winner, losers)
+
+# Winner gains rating by beating each loser individually
+# Losers only lose rating to the winner, not to each other
+```
+
+### Global Draw Recording
+
+```ruby
+EloRankable.record_draw(player1, player2)
+```
+
+### Accessing Rating Information
+
+```ruby
+player = Player.first
+
+player.elo_rating      # Current Elo rating
+player.games_played    # Number of games played
+player.elo_ranking     # Access to the full EloRanking record
+```
+
+### Accessing K-Factor Values
+
+```ruby
+# Get the K-factor for a specific rating
+EloRankable.config.k_factor_for(1500)  # => 32
+EloRankable.config.k_factor_for(2200)  # => 20
+```
+
+### Leaderboards and Scopes
+
+```ruby
+# Get players ordered by rating (highest first)
+top_players = Player.by_elo_rating
+
+# Get top 10 players
+top_10 = Player.top_rated(10)
+
+# Access EloRanking records directly
+top_ratings = EloRankable::EloRanking.by_rating.limit(10)
+```
+
+## Configuration
+
+### Base Rating
+
+```ruby
+EloRankable.configure do |config|
+  config.base_rating = 1500  # Default is 1200
+end
+```
+
+### K-Factor Strategy
+
+The K-factor determines how much ratings change after each match. You can use a constant value or a dynamic strategy based on rating:
+
+#### Constant K-Factor
+
+```ruby
+EloRankable.configure do |config|
+  config.k_factor_for = 32
+end
+```
+
+#### Dynamic K-Factor (Default)
+
+```ruby
+EloRankable.configure do |config|
+  config.k_factor_for = ->(rating) do
+    if rating > 2400
+      10   # Masters: smaller changes
+    elsif rating > 2000
+      20   # Experts: medium changes  
+    else
+      32   # Beginners: larger changes
+    end
+  end
+end
+```
+
+## Method Reference
+
+### Instance Methods (added by `has_elo_ranking`)
+
+| Method | Description |
+|--------|-------------|
+| `beat!(other)` | Record a win against another player |
+| `lost_to!(other)` | Record a loss to another player |
+| `draw_with!(other)` | Record a draw with another player |
+| `elo_beat!(other)` | Alias for `beat!` |
+| `elo_lost_to!(other)` | Alias for `lost_to!` |
+| `elo_draw_with!(other)` | Alias for `draw_with!` |
+| `elo_rating` | Current Elo rating |
+| `games_played` | Number of games played |
+| `elo_ranking` | Associated EloRanking record |
+
+### Class Methods (added by `has_elo_ranking`)
+
+| Scope | Description |
+|-------|-------------|
+| `by_elo_rating` | Order by Elo rating (highest first) |
+| `top_rated(limit)` | Get top N players by rating |
+
+### Module Methods
+
+| Method | Description |
+|--------|-------------|
+| `EloRankable.record_multiplayer_match(players)` | Record ranked multiplayer match |
+| `EloRankable.record_winner_vs_all(winner, losers)` | Record winner-takes-all match |
+| `EloRankable.record_draw(player1, player2)` | Record a draw |
+
+## How Elo Rating Works
+
+The Elo rating system calculates expected outcomes based on rating differences and adjusts ratings based on actual results:
+
+- **Expected Score**: Higher-rated players are expected to win more often
+- **Rating Change**: Beating a higher-rated opponent gives more points than beating a lower-rated one
+- **K-Factor**: Controls how much ratings can change (higher K = more volatile)
+
+### Example Calculation
+
+```ruby
+# Alice (1200) vs Bob (1200) - equal ratings
+alice.beat!(bob)
+# Alice: 1200 + 16 = 1216 (gained 16 points)
+# Bob:   1200 - 16 = 1184 (lost 16 points)
+
+# Alice (1400) vs Charlie (1200) - Alice favored
+alice.beat!(charlie)
+# Alice: 1400 + 8 = 1408 (gained 8 points - expected to win)
+# Charlie: 1200 - 8 = 1192 (lost 8 points)
+
+# Charlie (1192) beats Alice (1408) - upset!
+charlie.beat!(alice)
+# Charlie: 1192 + 24 = 1216 (gained 24 points - major upset)
+# Alice: 1408 - 24 = 1384 (lost 24 points)
+```
+
+
+## Error Handling
+
+The gem provides comprehensive validation with specific error types:
+
+### EloRankable::InvalidMatchError
+- Thrown when match requirements aren't met (e.g., less than 2 players)
+- Winner appears in losers list
+
+### ArgumentError
+- Nil players/opponents
+- Duplicate players in arrays
+- Players that don't respond to `elo_ranking`
+- Playing against yourself or destroyed records
+
+```ruby
+# Examples that will raise errors:
+alice.beat!(nil)                    # ArgumentError: Cannot play against nil
+alice.beat!(alice)                  # ArgumentError: Cannot play against yourself
+EloRankable.record_multiplayer_match([alice])  # InvalidMatchError: Need at least 2 players
+```
+
+
+## Database Schema
+
+The gem creates an `elo_rankings` table:
+
+```ruby
+create_table :elo_rankings do |t|
+  t.references :rankable, polymorphic: true, null: false, index: true
+  t.integer :rating, null: false, default: 1200
+  t.integer :games_played, null: false, default: 0
+  t.timestamps
+end
+
+add_index :elo_rankings, :rating
+add_index :elo_rankings, [:rankable_type, :rankable_id], unique: true
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/aberen/elo_rankable.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+require 'rubocop/rake_task'
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/elo_rankable.gemspec

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require_relative 'lib/elo_rankable/version'
+
+Gem::Specification.new do |spec|
+  spec.name = 'elo_rankable'
+  spec.version = EloRankable::VERSION
+  spec.authors = ['Aberen']
+  spec.email = ['nijoergensen@gmail.com']
+
+  spec.summary = 'Add Elo rating capabilities to any ActiveRecord model'
+  spec.description = 'Adds Elo rating to any ActiveRecord model via has_elo_ranking.'
+  spec.homepage = 'https://github.com/Aberen/elo_rankable'
+  spec.license = 'MIT'
+  spec.required_ruby_version = '>= 2.7.0'
+
+  spec.metadata['homepage_uri'] = spec.homepage
+  spec.metadata['source_code_uri'] = spec.homepage
+  spec.metadata['changelog_uri'] = "#{spec.homepage}/blob/main/CHANGELOG.md"
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  # Specify which files should be added to the gem when it is released.
+  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 Gemfile])
+    end
+  end
+  spec.bindir = 'exe'
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+
+  # Dependencies
+  spec.add_dependency 'activerecord', '>= 6.0', '< 8.0'
+  spec.add_dependency 'activesupport', '>= 6.0', '< 8.0'
+end

data/lib/elo_rankable/calculator.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module EloRankable
+  class Calculator
+    class << self
+      # Calculate expected score for player A against player B
+      def expected_score(rating_a, rating_b)
+        1.0 / (1.0 + (10.0**((rating_b - rating_a) / 400.0)))
+      end
+
+      # Update ratings after a match where player1 beats player2
+      def update_ratings_for_win(winner, loser)
+        winner_rating = winner.elo_ranking
+        loser_rating = loser.elo_ranking
+
+        # Defensive validation - these should be caught earlier but just in case
+        raise ArgumentError, "Winner's elo_ranking is nil" if winner_rating.nil?
+        raise ArgumentError, "Loser's elo_ranking is nil" if loser_rating.nil?
+
+        winner_expected = expected_score(winner_rating.rating, loser_rating.rating)
+        loser_expected = expected_score(loser_rating.rating, winner_rating.rating)
+
+        winner_k = winner_rating.k_factor
+        loser_k = loser_rating.k_factor
+
+        # Winner gets 1 point, loser gets 0 points
+        winner_new_rating = winner_rating.rating + (winner_k * (1 - winner_expected))
+        loser_new_rating = loser_rating.rating + (loser_k * (0 - loser_expected))
+
+        update_ranking(winner_rating, winner_new_rating)
+        update_ranking(loser_rating, loser_new_rating)
+      end
+
+      # Update ratings after a draw
+      def update_ratings_for_draw(player1, player2)
+        player1_rating = player1.elo_ranking
+        player2_rating = player2.elo_ranking
+
+        # Defensive validation - these should be caught earlier but just in case
+        raise ArgumentError, "Player1's elo_ranking is nil" if player1_rating.nil?
+        raise ArgumentError, "Player2's elo_ranking is nil" if player2_rating.nil?
+
+        player1_expected = expected_score(player1_rating.rating, player2_rating.rating)
+        player2_expected = expected_score(player2_rating.rating, player1_rating.rating)
+
+        player1_k = player1_rating.k_factor
+        player2_k = player2_rating.k_factor
+
+        # Both players get 0.5 points in a draw
+        player1_new_rating = player1_rating.rating + (player1_k * (0.5 - player1_expected))
+        player2_new_rating = player2_rating.rating + (player2_k * (0.5 - player2_expected))
+
+        update_ranking(player1_rating, player1_new_rating)
+        update_ranking(player2_rating, player2_new_rating)
+      end
+
+      private
+
+      def update_ranking(elo_ranking, new_rating)
+        elo_ranking.update!(
+          rating: new_rating.round,
+          games_played: elo_ranking.games_played + 1
+        )
+      end
+    end
+  end
+end

data/lib/elo_rankable/configuration.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module EloRankable
+  class Configuration
+    attr_accessor :base_rating
+    attr_reader :k_factor_strategy
+
+    def initialize
+      @base_rating = 1200
+      @k_factor_strategy = default_k_factor_strategy
+    end
+
+    def k_factor_for=(strategy)
+      @k_factor_strategy = strategy
+    end
+
+    def k_factor_for(rating)
+      case @k_factor_strategy
+      when Proc
+        @k_factor_strategy.call(rating)
+      when Numeric
+        @k_factor_strategy
+      else
+        raise ArgumentError, 'K-factor strategy must be a Proc or Numeric'
+      end
+    end
+
+    private
+
+    def default_k_factor_strategy
+      lambda do |rating|
+        if rating > 2400
+          10
+        elsif rating > 2000
+          20
+        else
+          32
+        end
+      end
+    end
+  end
+end

data/lib/elo_rankable/elo_ranking.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module EloRankable
+  class EloRanking < ActiveRecord::Base
+    belongs_to :rankable, polymorphic: true
+
+    validates :rating, presence: true, numericality: { greater_than: 0 }
+    validates :games_played, presence: true, numericality: { greater_than_or_equal_to: 0 }
+
+    scope :by_rating, -> { order(rating: :desc) }
+    scope :top, ->(limit = 10) { by_rating.limit(limit) }
+
+    def initialize(attributes = nil)
+      super
+      self.rating ||= EloRankable.config.base_rating
+      self.games_played ||= 0
+    end
+
+    def k_factor
+      EloRankable.config.k_factor_for(rating)
+    end
+  end
+end

data/lib/elo_rankable/has_elo_ranking.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module EloRankable
+  module HasEloRanking
+    def has_elo_ranking
+      # Set up the polymorphic association
+      has_one :elo_ranking, as: :rankable, class_name: 'EloRankable::EloRanking', dependent: :destroy
+
+      # Include instance methods
+      include InstanceMethods
+
+      # Add scopes for leaderboards
+      scope :by_elo_rating, -> { joins(:elo_ranking).order('elo_rankings.rating DESC') }
+      scope :top_rated, ->(limit = 10) { by_elo_rating.limit(limit) }
+    end
+
+    module InstanceMethods
+      def elo_ranking
+        super || create_elo_ranking!(
+          rating: EloRankable.config.base_rating,
+          games_played: 0
+        )
+      end
+
+      def elo_rating
+        elo_ranking.rating
+      end
+
+      def games_played
+        elo_ranking.games_played
+      end
+
+      # Domain-style DSL methods
+      def beat!(other_player)
+        validate_opponent!(other_player)
+        EloRankable::Calculator.update_ratings_for_win(self, other_player)
+      end
+
+      def lost_to!(other_player)
+        validate_opponent!(other_player)
+        EloRankable::Calculator.update_ratings_for_win(other_player, self)
+      end
+
+      def draw_with!(other_player)
+        validate_opponent!(other_player)
+        EloRankable::Calculator.update_ratings_for_draw(self, other_player)
+      end
+
+      # Aliases for clarity
+      alias elo_beat! beat!
+      alias elo_lost_to! lost_to!
+      alias elo_draw_with! draw_with!
+
+      private
+
+      def validate_opponent!(other_player)
+        raise ArgumentError, 'Cannot play against nil' if other_player.nil?
+        raise ArgumentError, 'Cannot play against yourself' if other_player == self
+        raise ArgumentError, 'Opponent must respond to elo_ranking' unless other_player.respond_to?(:elo_ranking)
+
+        # Check if the opponent is destroyed/deleted
+        if other_player.respond_to?(:destroyed?) && other_player.destroyed?
+          raise ArgumentError, 'Cannot play against a destroyed record'
+        end
+
+        # Get the elo_ranking once and validate it
+        opponent_ranking = other_player.elo_ranking
+        raise ArgumentError, "Opponent's elo_ranking is not initialized" if opponent_ranking.nil?
+        raise ArgumentError, "Opponent's elo_ranking is not saved" unless opponent_ranking.persisted?
+      end
+    end
+  end
+end

data/lib/elo_rankable/version.rb

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

data/lib/elo_rankable.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require 'active_record'
+require 'active_support'
+
+require_relative 'elo_rankable/version'
+require_relative 'elo_rankable/configuration'
+require_relative 'elo_rankable/elo_ranking'
+require_relative 'elo_rankable/calculator'
+require_relative 'elo_rankable/has_elo_ranking'
+
+# EloRankable provides methods for recording Elo-based ranking results for multiplayer matches,
+# winner-vs-all matches, and draws between players. It expects player objects to respond to
+# `elo_ranking` and `beat!` methods, and includes configuration support.
+#
+# Example usage:
+#   EloRankable.record_multiplayer_match([player1, player2, player3])
+#   EloRankable.record_winner_vs_all(winner, [loser1, loser2])
+#   EloRankable.record_draw(player1, player2)
+#
+# Configuration can be customized via EloRankable.configure.
+#
+# Errors:
+#   EloRankable::InvalidMatchError - Raised for invalid match scenarios.
+#   ArgumentError - Raised for invalid arguments or player objects.
+module EloRankable
+  class Error < StandardError; end
+  class InvalidMatchError < Error; end
+
+  class << self
+    def config
+      @config ||= Configuration.new
+    end
+
+    def configure
+      yield(config) if block_given?
+    end
+
+    # Record a multiplayer match where players are ranked by their position in the array
+    # Higher-indexed players are treated as having lost to lower-indexed ones
+    def record_multiplayer_match(players)
+      raise InvalidMatchError, 'Need at least 2 players for a match' if players.length < 2
+
+      # Validate input array
+      raise ArgumentError, 'Players array cannot contain nil values' if players.any?(&:nil?)
+
+      # Check for duplicates
+      raise ArgumentError, 'Players array cannot contain duplicate players' if players.uniq.length != players.length
+
+      # Validate all players respond to elo_ranking
+      invalid_players = players.reject { |p| p.respond_to?(:elo_ranking) }
+      raise ArgumentError, 'All players must respond to elo_ranking' unless invalid_players.empty?
+
+      # Process all pairwise combinations
+      players.each_with_index do |player1, i|
+        players[(i + 1)..].each do |player2|
+          player1.beat!(player2)
+        end
+      end
+    end
+
+    # Record a single winner vs all others match
+    def record_winner_vs_all(winner, losers)
+      # Validate winner
+      raise ArgumentError, 'Winner cannot be nil' if winner.nil?
+      raise ArgumentError, 'Winner must respond to elo_ranking' unless winner.respond_to?(:elo_ranking)
+
+      # Validate losers array
+      raise InvalidMatchError, 'Need at least 1 loser' if losers.empty?
+      raise ArgumentError, 'Losers array cannot contain nil values' if losers.any?(&:nil?)
+      raise InvalidMatchError, 'Winner cannot be in losers list' if losers.include?(winner)
+
+      # Validate all losers respond to elo_ranking
+      invalid_losers = losers.reject { |p| p.respond_to?(:elo_ranking) }
+      raise ArgumentError, 'All losers must respond to elo_ranking' unless invalid_losers.empty?
+
+      losers.each do |loser|
+        winner.beat!(loser)
+      end
+    end
+
+    # Record a draw between two players
+    def record_draw(player1, player2)
+      raise ArgumentError, 'Player1 cannot be nil' if player1.nil?
+      raise ArgumentError, 'Player2 cannot be nil' if player2.nil?
+      raise ArgumentError, 'Cannot record draw with same player' if player1 == player2
+      raise ArgumentError, 'Player1 must respond to elo_ranking' unless player1.respond_to?(:elo_ranking)
+      raise ArgumentError, 'Player2 must respond to elo_ranking' unless player2.respond_to?(:elo_ranking)
+
+      Calculator.update_ratings_for_draw(player1, player2)
+    end
+  end
+end
+
+# Hook into ActiveRecord
+ActiveRecord::Base.extend(EloRankable::HasEloRanking) if defined?(ActiveRecord::Base)

data/lib/generators/elo_rankable/install/install_generator.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require 'rails/generators/active_record'
+
+module EloRankable
+  module Generators
+    class InstallGenerator < ActiveRecord::Generators::Base
+      desc 'Create migration for EloRankable'
+
+      source_root File.expand_path('templates', __dir__)
+
+      def self.default_generator_root
+        File.dirname(__FILE__)
+      end
+
+      def create_migration_file
+        migration_template 'create_elo_rankings.rb', 'db/migrate/create_elo_rankings.rb'
+      end
+    end
+  end
+end

data/lib/generators/elo_rankable/install/templates/create_elo_rankings.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+class CreateEloRankings < ActiveRecord::Migration[6.0]
+  def change
+    create_table :elo_rankings do |t|
+      t.references :rankable, polymorphic: true, null: false, index: true
+      t.integer :rating, null: false, default: 1200
+      t.integer :games_played, null: false, default: 0
+
+      t.timestamps
+    end
+
+    add_index :elo_rankings, :rating
+    add_index :elo_rankings, %i[rankable_type rankable_id], unique: true
+  end
+end

metadata

@@ -0,0 +1,102 @@
+--- !ruby/object:Gem::Specification
+name: elo_rankable
+version: !ruby/object:Gem::Version
+  version: 0.1.2
+platform: ruby
+authors:
+- Aberen
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2025-08-06 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8.0'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8.0'
+description: Adds Elo rating to any ActiveRecord model via has_elo_ranking.
+email:
+- nijoergensen@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- ".rubocop.yml"
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- elo_rankable.gemspec
+- lib/elo_rankable.rb
+- lib/elo_rankable/calculator.rb
+- lib/elo_rankable/configuration.rb
+- lib/elo_rankable/elo_ranking.rb
+- lib/elo_rankable/has_elo_ranking.rb
+- lib/elo_rankable/version.rb
+- lib/generators/elo_rankable/install/install_generator.rb
+- lib/generators/elo_rankable/install/templates/create_elo_rankings.rb
+homepage: https://github.com/Aberen/elo_rankable
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/Aberen/elo_rankable
+  source_code_uri: https://github.com/Aberen/elo_rankable
+  changelog_uri: https://github.com/Aberen/elo_rankable/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.11
+signing_key: 
+specification_version: 4
+summary: Add Elo rating capabilities to any ActiveRecord model
+test_files: []