mlb 0.10.0 → 0.11.0

data/lib/mlb/leader.rb

@@ -0,0 +1,79 @@
+require "equalizer"
+require "shale"
+require_relative "player"
+require_relative "team"
+require_relative "league"
+require_relative "sport"
+
+module MLB
+  # Represents a league leader
+  class Leader < Shale::Mapper
+    include Equalizer.new(:rank, :person)
+
+    # @!attribute [rw] rank
+    #   Returns the leader rank
+    #   @api public
+    #   @example
+    #     leader.rank #=> 1
+    #   @return [Integer] the rank
+    attribute :rank, Shale::Type::Integer
+
+    # @!attribute [rw] value
+    #   Returns the stat value
+    #   @api public
+    #   @example
+    #     leader.value #=> "58"
+    #   @return [String] the value
+    attribute :value, Shale::Type::String
+
+    # @!attribute [rw] person
+    #   Returns the player
+    #   @api public
+    #   @example
+    #     leader.person #=> #<MLB::Player>
+    #   @return [Player] the player
+    attribute :person, Player
+
+    # @!attribute [rw] team
+    #   Returns the team
+    #   @api public
+    #   @example
+    #     leader.team #=> #<MLB::Team>
+    #   @return [Team] the team
+    attribute :team, Team
+
+    # @!attribute [rw] league
+    #   Returns the league
+    #   @api public
+    #   @example
+    #     leader.league #=> #<MLB::League>
+    #   @return [League] the league
+    attribute :league, League
+
+    # @!attribute [rw] sport
+    #   Returns the sport
+    #   @api public
+    #   @example
+    #     leader.sport #=> #<MLB::Sport>
+    #   @return [Sport] the sport
+    attribute :sport, Sport
+
+    # @!attribute [rw] season
+    #   Returns the season
+    #   @api public
+    #   @example
+    #     leader.season #=> "2024"
+    #   @return [String] the season
+    attribute :season, Shale::Type::String
+
+    json do
+      map "rank", to: :rank
+      map "value", to: :value
+      map "person", to: :person
+      map "team", to: :team
+      map "league", to: :league
+      map "sport", to: :sport
+      map "season", to: :season
+    end
+  end
+end

data/lib/mlb/leaders.rb

@@ -0,0 +1,68 @@
+require "shale"
+require_relative "leader"
+
+module MLB
+  # Represents a leader category result
+  class LeaderCategory < Shale::Mapper
+    # @!attribute [rw] leader_category
+    #   Returns the category name
+    #   @api public
+    #   @example
+    #     category.leader_category #=> "homeRuns"
+    #   @return [String] the category
+    attribute :leader_category, Shale::Type::String
+
+    # @!attribute [rw] season
+    #   Returns the season
+    #   @api public
+    #   @example
+    #     category.season #=> "2024"
+    #   @return [String] the season
+    attribute :season, Shale::Type::String
+
+    # @!attribute [rw] leaders
+    #   Returns the leaders
+    #   @api public
+    #   @example
+    #     category.leaders #=> [#<MLB::Leader>, ...]
+    #   @return [Array<Leader>] the leaders
+    attribute :leaders, Leader, collection: true
+
+    json do
+      map "leaderCategory", to: :leader_category
+      map "season", to: :season
+      map "leaders", to: :leaders
+    end
+  end
+
+  # Provides methods for fetching league leaders from the API
+  class Leaders < Shale::Mapper
+    # @!attribute [rw] league_leaders
+    #   Returns the league leaders
+    #   @api public
+    #   @example
+    #     leaders.league_leaders #=> [#<MLB::LeaderCategory>, ...]
+    #   @return [Array<LeaderCategory>] the league leaders
+    attribute :league_leaders, LeaderCategory, collection: true
+
+    json do
+      map "leagueLeaders", to: :league_leaders
+    end
+
+    # Retrieves league leaders for a category
+    #
+    # @api public
+    # @example Get home run leaders
+    #   MLB::Leaders.find(category: "homeRuns", season: 2024)
+    # @param category [String] the stat category
+    # @param season [Integer, nil] the season year (defaults to current year)
+    # @param limit [Integer] the number of leaders to return (defaults to 10)
+    # @return [Array<Leader>] the leaders
+    def self.find(category:, season: nil, limit: 10)
+      season ||= Utils.current_season
+      params = {leaderCategories: category, season:, limit:}
+      response = CLIENT.get("stats/leaders?#{Utils.build_query(params)}")
+      from_json(response).league_leaders.first&.leaders || []
+    end
+  end
+end

data/lib/mlb/league.rb

@@ -1,20 +1,34 @@
 require "equalizer"
 require "shale"
+require_relative "comparable_by_attribute"
 require_relative "season_date_info"
 require_relative "sport"
 
 module MLB
+  # Represents a league (e.g., American League, National League)
   class League < Shale::Mapper
     include Comparable
+    include ComparableByAttribute
     include Equalizer.new(:id)
 
+    SEASON_PRESEASON = "preseason".freeze
+    SEASON_INSEASON = "inseason".freeze
+    SEASON_POSTSEASON = "postseason".freeze
+    SEASON_OFFSEASON = "offseason".freeze
+
+    # Returns the attribute used for sorting
+    #
+    # @api private
+    # @return [Symbol] the attribute used for comparison
+    def comparable_attribute = :sort_order
+
     attribute :id, Shale::Type::Integer
     attribute :name, Shale::Type::String
     attribute :link, Shale::Type::String
     attribute :abbreviation, Shale::Type::String
     attribute :name_short, Shale::Type::String
     attribute :season_state, Shale::Type::String
-    attribute :has_wild_card, Shale::Type::Boolean
+    attribute :has_wildcard, Shale::Type::Boolean
     attribute :has_split_season, Shale::Type::Boolean
     attribute :num_games, Shale::Type::Integer
     attribute :has_playoff_points, Shale::Type::Boolean
@@ -29,14 +43,85 @@ module MLB
     attribute :sort_order, Shale::Type::Integer
     attribute :active, Shale::Type::Boolean
 
-    alias_method :active?, :active
-    alias_method :wild_card?, :has_wild_card
-    alias_method :has_wildcard, :has_wild_card
-    alias_method :wildcard?, :has_wild_card
-    alias_method :split_season?, :has_split_season
-    alias_method :playoff_points?, :has_playoff_points
-    alias_method :conferences?, :conferences_in_use
-    alias_method :divisions?, :divisions_in_use
+    # Checks if the league is active
+    #
+    # @api public
+    # @example
+    #   league.active? #=> true
+    # @return [Boolean] whether the league is active
+    def active? = active
+
+    # Checks if the league has a wildcard
+    #
+    # @api public
+    # @example
+    #   league.wildcard? #=> true
+    # @return [Boolean] whether the league has a wildcard
+    def wildcard? = has_wildcard
+
+    # Checks if the league has a split season
+    #
+    # @api public
+    # @example
+    #   league.split_season? #=> false
+    # @return [Boolean] whether the league has a split season
+    def split_season? = has_split_season
+
+    # Checks if the league uses playoff points
+    #
+    # @api public
+    # @example
+    #   league.playoff_points? #=> false
+    # @return [Boolean] whether the league uses playoff points
+    def playoff_points? = has_playoff_points
+
+    # Checks if the league uses conferences
+    #
+    # @api public
+    # @example
+    #   league.conferences? #=> false
+    # @return [Boolean] whether the league uses conferences
+    def conferences? = conferences_in_use
+
+    # Checks if the league uses divisions
+    #
+    # @api public
+    # @example
+    #   league.divisions? #=> true
+    # @return [Boolean] whether the league uses divisions
+    def divisions? = divisions_in_use
+
+    # Checks if the league is in preseason
+    #
+    # @api public
+    # @example
+    #   league.preseason? #=> false
+    # @return [Boolean] whether the league is in preseason
+    def preseason? = season_state.eql?(SEASON_PRESEASON)
+
+    # Checks if the league is in season
+    #
+    # @api public
+    # @example
+    #   league.in_season? #=> true
+    # @return [Boolean] whether the league is in season
+    def in_season? = season_state.eql?(SEASON_INSEASON)
+
+    # Checks if the league is in postseason
+    #
+    # @api public
+    # @example
+    #   league.postseason? #=> false
+    # @return [Boolean] whether the league is in postseason
+    def postseason? = season_state.eql?(SEASON_POSTSEASON)
+
+    # Checks if the league is in offseason
+    #
+    # @api public
+    # @example
+    #   league.offseason? #=> false
+    # @return [Boolean] whether the league is in offseason
+    def offseason? = season_state.eql?(SEASON_OFFSEASON)
 
     json do
       map "id", to: :id
@@ -45,7 +130,7 @@ module MLB
       map "abbreviation", to: :abbreviation
       map "nameShort", to: :name_short
       map "seasonState", to: :season_state
-      map "hasWildCard", to: :has_wild_card
+      map "hasWildCard", to: :has_wildcard
       map "hasSplitSeason", to: :has_split_season
       map "numGames", to: :num_games
       map "hasPlayoffPoints", to: :has_playoff_points
@@ -60,9 +145,5 @@ module MLB
       map "sortOrder", to: :sort_order
       map "active", to: :active
     end
-
-    def <=>(other)
-      sort_order <=> other.sort_order
-    end
   end
 end

data/lib/mlb/league_leader_type.rb

@@ -0,0 +1,21 @@
+require "equalizer"
+require "shale"
+
+module MLB
+  # Represents a league leader statistic type
+  class LeagueLeaderType < Shale::Mapper
+    include Equalizer.new(:display_name)
+
+    # @!attribute [rw] display_name
+    #   Returns the display name for the leader type
+    #   @api public
+    #   @example
+    #     league_leader_type.display_name #=> "homeRuns"
+    #   @return [String] the display name for the leader type
+    attribute :display_name, Shale::Type::String
+
+    json do
+      map "displayName", to: :display_name
+    end
+  end
+end

data/lib/mlb/league_leader_types.rb

@@ -0,0 +1,12 @@
+require_relative "collection"
+require_relative "league_leader_type"
+
+module MLB
+  # Provides methods for fetching league leader types from the API
+  #
+  # @example Fetch all league leader types
+  #   MLB::LeagueLeaderTypes.all #=> [#<MLB::LeagueLeaderType>, ...]
+  class LeagueLeaderTypes < Collection
+    collection endpoint: "leagueLeaderTypes", item_type: LeagueLeaderType, collection_name: :league_leader_types
+  end
+end

data/lib/mlb/leagues.rb

@@ -1,30 +1,36 @@
 require "shale"
-require "uri"
-require_relative "sport"
 require_relative "league"
 
 module MLB
+  # Collection of leagues from the MLB Stats API
   class Leagues < Shale::Mapper
-    attribute :copyright, Shale::Type::String
     attribute :leagues, League, collection: true
 
-    def self.all(sport: Sport.new(id: 1))
-      sport_id = sport.respond_to?(:id) ? sport.id : sport
-      params = {sportId: sport_id}
-      query_string = URI.encode_www_form(params)
-      response = CLIENT.get("leagues?#{query_string}")
-      leagues = from_json(response)
-      leagues.leagues.sort!
+    # Retrieves all leagues
+    #
+    # @api public
+    # @example
+    #   MLB::Leagues.all
+    # @param sport [Integer, Sport] the sport ID or Sport object
+    # @return [Array<League>] list of all leagues
+    def self.all(sport: Utils::DEFAULT_SPORT_ID)
+      params = {sportId: Utils.extract_id(sport)}
+      response = CLIENT.get("leagues?#{Utils.build_query(params)}")
+      from_json(response).leagues.sort
     end
 
-    def self.find(league, sport: Sport.new(id: 1))
-      id = league.respond_to?(:id) ? league.id : league
-      sport_id = sport.respond_to?(:id) ? sport.id : sport
-      params = {sportId: sport_id}
-      query_string = URI.encode_www_form(params)
-      response = CLIENT.get("leagues/#{id}?#{query_string}")
-      leagues = from_json(response)
-      leagues.leagues.sort!.first
+    # Finds a league by ID
+    #
+    # @api public
+    # @example
+    #   MLB::Leagues.find(103)
+    # @param league [Integer, League] the league ID or League object
+    # @param sport [Integer, Sport] the sport ID or Sport object
+    # @return [League, nil] the league if found
+    def self.find(league, sport: Utils::DEFAULT_SPORT_ID)
+      params = {sportId: Utils.extract_id(sport)}
+      response = CLIENT.get("leagues/#{Utils.extract_id(league)}?#{Utils.build_query(params)}")
+      from_json(response).leagues.min_by { |l| l.sort_order || 0 }
     end
   end
 end