@quenty/elo 7.19.0 → 7.19.1

package/CHANGELOG.md

@@ -3,6 +3,17 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [7.19.1](https://github.com/Quenty/NevermoreEngine/compare/@quenty/elo@7.19.0...@quenty/elo@7.19.1) (2025-04-05)
+
+
+### Bug Fixes
+
+* Add types to packages ([2374fb2](https://github.com/Quenty/NevermoreEngine/commit/2374fb2b043cfbe0e9b507b3316eec46a4e353a0))
+
+
+
+
+
 # [7.19.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/elo@7.18.2...@quenty/elo@7.19.0) (2025-04-02)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quenty/elo",
-  "version": "7.19.0",
+  "version": "7.19.1",
   "description": "Elo rating utility library.",
   "keywords": [
     "Roblox",
@@ -29,12 +29,12 @@
     "access": "public"
   },
   "devDependencies": {
-    "@quenty/blend": "^12.18.0",
-    "@quenty/loader": "^10.8.0",
-    "@quenty/maid": "^3.4.0"
+    "@quenty/blend": "^12.18.1",
+    "@quenty/loader": "^10.8.1",
+    "@quenty/maid": "^3.4.1"
   },
   "dependencies": {
     "@quenty/probability": "^2.3.1"
   },
-  "gitHead": "e8ea56930e65322fcffc05a1556d5df988068f0b"
+  "gitHead": "78c3ac0ab08dd18085b6e6e6e4f745e76ed99f68"
 }

package/src/Shared/EloMatchResult.lua

@@ -1,9 +1,8 @@
+--!strict
 --[=[
 	@class EloMatchResult
 ]=]
 
-local require = require(script.Parent.loader).load(script)
-
 return table.freeze(setmetatable({
 	PLAYER_ONE_WIN = 1;
 	DRAW = 0.5;

package/src/Shared/EloMatchResultUtils.lua

@@ -1,3 +1,4 @@
+--!strict
 --[=[
 	@class EloMatchResultUtils
 ]=]
@@ -8,18 +9,30 @@ local EloMatchResult = require("EloMatchResult")
 
 local EloMatchResultUtils = {}
 
-function EloMatchResultUtils.isEloMatchResult(matchResult)
+--[=[
+	Checks if the given match result is a valid EloMatchResult.
+
+	@param matchResult any
+	@return boolean
+]=]
+function EloMatchResultUtils.isEloMatchResult(matchResult: any): boolean
 	return matchResult == EloMatchResult.PLAYER_ONE_WIN
 		or matchResult == EloMatchResult.PLAYER_TWO_WIN
 		or matchResult == EloMatchResult.DRAW
 end
 
-function EloMatchResultUtils.isEloMatchResultList(eloMatchResultList)
+--[=[
+	Checks if the given match result is a valid EloMatchResult list
+
+	@param eloMatchResultList any
+	@return boolean
+]=]
+function EloMatchResultUtils.isEloMatchResultList(eloMatchResultList: {number }): boolean
 	if type(eloMatchResultList) ~= "table" then
 		return false
 	end
 
-	for _, eloMatchResult in pairs(eloMatchResultList) do
+	for _, eloMatchResult in eloMatchResultList do
 		if not EloMatchResultUtils.isEloMatchResult(eloMatchResult) then
 			return false
 		end

package/src/Shared/EloUtils.lua

@@ -1,3 +1,4 @@
+--!strict
 --[=[
 	Utilities to compute elo scores for players
 	@class EloUtils
@@ -30,6 +31,8 @@ local Probability = require("Probability")
 
 local EloUtils = {}
 
+export type EloMatchResultList = { number }
+
 --[=[
 	@interface EloConfig
 	.factor number
@@ -39,21 +42,36 @@ local EloUtils = {}
 	.groupMultipleResultAsOne boolean
 	@within EloUtils
 ]=]
+export type EloConfig = {
+	factor: number,
+	kfactor: number | (rating: number) -> number,
+	initial: number,
+	ratingFloor: number,
+	groupMultipleResultAsOne: boolean,
+}
+
+export type PartialEloConfig = {
+	factor: number?,
+	kfactor: (number | (rating: number) -> number)?,
+	initial: number?,
+	ratingFloor: number?,
+	groupMultipleResultAsOne: boolean?,
+}
 
 --[=[
 	Creates a new elo config.
 	@param config table? -- Optional table with defaults
 	@return EloConfig
 ]=]
-function EloUtils.createConfig(config)
-	config = config or {}
+function EloUtils.createConfig(config: PartialEloConfig?): EloConfig
+	local partial: PartialEloConfig = config or {}
 
 	return {
-		factor = config.factor or 400;
-		kfactor = config.kfactor or EloUtils.standardKFactorFormula;
-		initial = config.initial or 1400;
-		ratingFloor = config.ratingFloor or 100;
-		groupMultipleResultAsOne = false;
+		factor = partial.factor or 400,
+		kfactor = partial.kfactor or EloUtils.standardKFactorFormula,
+		initial = partial.initial or 1400,
+		ratingFloor = partial.ratingFloor or 100,
+		groupMultipleResultAsOne = false,
 	}
 end
 
@@ -63,7 +81,7 @@ end
 	@param config any
 	@return boolean
 ]=]
-function EloUtils.isEloConfig(config)
+function EloUtils.isEloConfig(config: EloConfig): boolean
 	return type(config) == "table"
 		and type(config.factor) == "number"
 		and (type(config.kfactor) == "number" or type(config.kfactor) == "function")
@@ -78,10 +96,10 @@ end
 	@param eloConfig EloConfig
 	@return number
 ]=]
-function EloUtils.getStandardDeviation(eloConfig)
+function EloUtils.getStandardDeviation(eloConfig: EloConfig): number
 	assert(EloUtils.isEloConfig(eloConfig), "Bad eloConfig")
 
-	return 0.5*eloConfig.factor*math.sqrt(2)
+	return 0.5 * eloConfig.factor * math.sqrt(2)
 end
 
 --[=[
@@ -91,13 +109,13 @@ end
 	@param elo number
 	@return number
 ]=]
-function EloUtils.getPercentile(eloConfig, elo)
+function EloUtils.getPercentile(eloConfig: EloConfig, elo: number): number
 	assert(EloUtils.isEloConfig(eloConfig), "Bad eloConfig")
 
 	local standardDeviation = EloUtils.getStandardDeviation(eloConfig)
 	local mean = eloConfig.initial
 
-	local zScore = (elo - mean)/standardDeviation
+	local zScore = (elo - mean) / standardDeviation
 	return Probability.cdf(zScore)
 end
 
@@ -108,14 +126,18 @@ end
 	@param percentile number
 	@return number
 ]=]
-function EloUtils.percentileToElo(eloConfig, percentile)
+function EloUtils.percentileToElo(eloConfig: EloConfig, percentile: number): number?
 	assert(EloUtils.isEloConfig(eloConfig), "Bad eloConfig")
 
 	local standardDeviation = EloUtils.getStandardDeviation(eloConfig)
 	local mean = eloConfig.initial
 
 	local zScore = Probability.percentileToZScore(percentile)
-	return mean + zScore*standardDeviation
+	if zScore == nil then
+		return nil
+	end
+
+	return mean + zScore * standardDeviation
 end
 
 --[=[
@@ -128,14 +150,25 @@ end
 	@return number -- playerOneRating
 	@return number -- playerTwoRating
 ]=]
-function EloUtils.getNewElo(config, playerOneRating, playerTwoRating, eloMatchResultList)
+function EloUtils.getNewElo(
+	config: EloConfig,
+	playerOneRating: number,
+	playerTwoRating: number,
+	eloMatchResultList: EloMatchResultList
+): (number, number)
 	assert(EloUtils.isEloConfig(config), "Bad config")
 	assert(type(playerOneRating) == "number", "Bad playerOneRating")
 	assert(type(playerTwoRating) == "number", "Bad playerTwoRating")
 	assert(EloMatchResultUtils.isEloMatchResultList(eloMatchResultList), "Bad eloMatchResultList")
 
-	local newPlayerOneRating = EloUtils.getNewPlayerOneScore(config, playerOneRating, playerTwoRating, eloMatchResultList)
-	local newPlayerTwoRating = EloUtils.getNewPlayerOneScore(config, playerTwoRating, playerOneRating, EloUtils.fromOpponentPerspective(eloMatchResultList))
+	local newPlayerOneRating =
+		EloUtils.getNewPlayerOneScore(config, playerOneRating, playerTwoRating, eloMatchResultList)
+	local newPlayerTwoRating = EloUtils.getNewPlayerOneScore(
+		config,
+		playerTwoRating,
+		playerOneRating,
+		EloUtils.fromOpponentPerspective(eloMatchResultList)
+	)
 	return newPlayerOneRating, newPlayerTwoRating
 end
 
@@ -149,13 +182,14 @@ end
 	@return number -- playerOneRating
 	@return number -- playerTwoRating
 ]=]
-function EloUtils.getEloChange(config, playerOneRating, playerTwoRating, eloMatchResultList)
+function EloUtils.getEloChange(config: EloConfig, playerOneRating: number, playerTwoRating: number, eloMatchResultList)
 	assert(EloUtils.isEloConfig(config), "Bad config")
 	assert(type(playerOneRating) == "number", "Bad playerOneRating")
 	assert(type(playerTwoRating) == "number", "Bad playerTwoRating")
 	assert(EloMatchResultUtils.isEloMatchResultList(eloMatchResultList), "Bad eloMatchResultList")
 
-	local newPlayerOneRating, newPlayerTwoRating = EloUtils.getNewElo(config, playerOneRating, playerTwoRating, eloMatchResultList)
+	local newPlayerOneRating, newPlayerTwoRating =
+		EloUtils.getNewElo(config, playerOneRating, playerTwoRating, eloMatchResultList)
 	local playerOneChange = newPlayerOneRating - playerOneRating
 	local playerTwoChange = newPlayerTwoRating - playerTwoRating
 	return playerOneChange, playerTwoChange
@@ -169,13 +203,22 @@ end
 	@param playerTwoRating number
 	@param eloMatchResultList { EloMatchResult }
 ]=]
-function EloUtils.getNewPlayerOneScore(config, playerOneRating, playerTwoRating, eloMatchResultList)
+function EloUtils.getNewPlayerOneScore(
+	config: EloConfig,
+	playerOneRating: number,
+	playerTwoRating: number,
+	eloMatchResultList: EloMatchResultList
+)
 	assert(EloUtils.isEloConfig(config), "Bad config")
 	assert(type(playerOneRating) == "number", "Bad playerOneRating")
 	assert(type(playerTwoRating) == "number", "Bad playerTwoRating")
 	assert(EloMatchResultUtils.isEloMatchResultList(eloMatchResultList), "Bad eloMatchResultList")
 
-	return math.max(config.ratingFloor, playerOneRating + EloUtils.getPlayerOneScoreAdjustment(config, playerOneRating, playerTwoRating, eloMatchResultList))
+	return math.max(
+		config.ratingFloor,
+		playerOneRating
+			+ EloUtils.getPlayerOneScoreAdjustment(config, playerOneRating, playerTwoRating, eloMatchResultList)
+	)
 end
 
 --[=[
@@ -190,7 +233,7 @@ end
 	@param playerTwoRating number
 	@return number
 ]=]
-function EloUtils.getPlayerOneExpected(config, playerOneRating, playerTwoRating)
+function EloUtils.getPlayerOneExpected(config: EloConfig, playerOneRating: number, playerTwoRating: number): number
 	assert(EloUtils.isEloConfig(config), "Bad config")
 	assert(type(playerOneRating) == "number", "Bad playerOneRating")
 	assert(type(playerTwoRating) == "number", "Bad playerTwoRating")
@@ -208,7 +251,12 @@ end
 	@param eloMatchResultList { EloMatchResult }
 	@return number
 ]=]
-function EloUtils.getPlayerOneScoreAdjustment(config, playerOneRating, playerTwoRating, eloMatchResultList)
+function EloUtils.getPlayerOneScoreAdjustment(
+	config: EloConfig,
+	playerOneRating: number,
+	playerTwoRating: number,
+	eloMatchResultList: EloMatchResultList
+): number
 	assert(EloUtils.isEloConfig(config), "Bad config")
 	assert(type(playerOneRating) == "number", "Bad playerOneRating")
 	assert(type(playerTwoRating) == "number", "Bad playerTwoRating")
@@ -229,15 +277,15 @@ function EloUtils.getPlayerOneScoreAdjustment(config, playerOneRating, playerTwo
 			multiplier = losses
 		end
 
-		adjustment = multiplier*(score - expected)
+		adjustment = multiplier * (score - expected)
 	else
-		for _, score in pairs(eloMatchResultList) do
+		for _, score in eloMatchResultList do
 			adjustment = adjustment + (score - expected)
 		end
 	end
 
 	local kfactor = EloUtils.extractKFactor(config, playerOneRating)
-	return kfactor*adjustment
+	return kfactor * adjustment
 end
 
 --[=[
@@ -246,12 +294,12 @@ end
 	@param eloMatchResultList { EloMatchResult }
 	@return { number }
 ]=]
-function EloUtils.fromOpponentPerspective(eloMatchResultList)
+function EloUtils.fromOpponentPerspective(eloMatchResultList: EloMatchResultList): EloMatchResultList
 	assert(EloMatchResultUtils.isEloMatchResultList(eloMatchResultList), "Bad eloMatchResultList")
 
 	local newScores = {}
 
-	for index, score in pairs(eloMatchResultList) do
+	for index, score in eloMatchResultList do
 		newScores[index] = 1 - score
 	end
 
@@ -264,11 +312,11 @@ end
 	@param eloMatchResultList { EloMatchResult }
 	@return { number }
 ]=]
-function EloUtils.countPlayerOneWins(eloMatchResultList)
+function EloUtils.countPlayerOneWins(eloMatchResultList: EloMatchResultList): number
 	assert(EloMatchResultUtils.isEloMatchResultList(eloMatchResultList), "Bad eloMatchResultList")
 
 	local count = 0
-	for _, score in pairs(eloMatchResultList) do
+	for _, score in eloMatchResultList do
 		if score == EloMatchResult.PLAYER_ONE_WIN then
 			count = count + 1
 		end
@@ -282,11 +330,11 @@ end
 	@param eloMatchResultList { EloMatchResult }
 	@return { number }
 ]=]
-function EloUtils.countPlayerTwoWins(eloMatchResultList)
+function EloUtils.countPlayerTwoWins(eloMatchResultList: EloMatchResultList): number
 	assert(EloMatchResultUtils.isEloMatchResultList(eloMatchResultList), "Bad eloMatchResultList")
 
 	local count = 0
-	for _, score in pairs(eloMatchResultList) do
+	for _, score in eloMatchResultList do
 		if score == EloMatchResult.PLAYER_TWO_WIN then
 			count = count + 1
 		end
@@ -300,7 +348,7 @@ end
 	@param rating number
 	@return number
 ]=]
-function EloUtils.standardKFactorFormula(rating)
+function EloUtils.standardKFactorFormula(rating: number): number
 	if rating >= 2400 then
 		return 16
 	elseif rating >= 2100 then
@@ -317,7 +365,7 @@ end
 	@param rating number
 	@return number
 ]=]
-function EloUtils.extractKFactor(config, rating)
+function EloUtils.extractKFactor(config: EloConfig, rating: number): number
 	assert(EloUtils.isEloConfig(config), "Bad config")
 	assert(type(rating) == "number", "Bad rating")
 

package/src/Shared/EloUtils.story.lua

@@ -21,7 +21,7 @@ local function TextLabel(props)
 		TextSize = props.TextSize or 20;
 		Text = props.Text;
 		RichText = props.RichText;
-	};
+	}
 end
 
 local function MatchResultCard(props)
@@ -294,7 +294,7 @@ return function(target)
 				};
 			}
 
-			for _, matchResultType in pairs(matchResultTypes) do
+			for _, matchResultType in matchResultTypes do
 				if type(matchResultType) == "string" then
 					table.insert(groupOptions, TextLabel({
 						TextColor3 = Color3.new(1, 1, 1);