@quenty/randomutils 6.9.0 → 6.9.1

package/CHANGELOG.md

@@ -3,6 +3,14 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [6.9.1](https://github.com/Quenty/NevermoreEngine/compare/@quenty/randomutils@6.9.0...@quenty/randomutils@6.9.1) (2025-03-21)
+
+**Note:** Version bump only for package @quenty/randomutils
+
+
+
+
+
 # [6.9.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/randomutils@6.8.0...@quenty/randomutils@6.9.0) (2025-02-18)
 
 **Note:** Version bump only for package @quenty/randomutils

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quenty/randomutils",
-  "version": "6.9.0",
+  "version": "6.9.1",
   "description": "Quenty's RandomUtils, utility functions for Roblox",
   "keywords": [
     "Roblox",
@@ -30,7 +30,7 @@
   },
   "dependencies": {
     "@quenty/loader": "^10.8.0",
-    "@quenty/table": "^3.7.0"
+    "@quenty/table": "^3.7.1"
   },
-  "gitHead": "184a407d8d7366c39009444c3c9a7023cb176471"
+  "gitHead": "6b7c3e15e60cdb185986207b574e2b5591261e7a"
 }

package/src/Shared/RandomSampler.lua

@@ -10,6 +10,12 @@ local RandomSampler = {}
 RandomSampler.ClassName = "RandomSampler"
 RandomSampler.__index = RandomSampler
 
+--[=[
+	Constructs a new RandomSampler
+
+	@param samples { T } -- The list of samples to sample from
+	@return RandomSampler<T>
+]=]
 function RandomSampler.new(samples)
 	local self = setmetatable({}, RandomSampler)
 
@@ -23,6 +29,11 @@ function RandomSampler.new(samples)
 	return self
 end
 
+--[=[
+	Sets the samples to sample from
+
+	@param samples { T } -- The list of samples to sample from
+]=]
 function RandomSampler:SetSamples(samples)
 	assert(type(samples) == "table", "Bad samples")
 
@@ -34,6 +45,11 @@ function RandomSampler:SetSamples(samples)
 	end
 end
 
+--[=[
+	Samples from the list
+
+	@return T -- The sample
+]=]
 function RandomSampler:Sample()
 	if #self._shuffledAvailableList == 0 then
 		self:Refill()
@@ -45,6 +61,9 @@ function RandomSampler:Sample()
 	return selection
 end
 
+--[=[
+	Refills the list
+]=]
 function RandomSampler:Refill()
 	local newList = RandomUtils.shuffledCopy(self._optionsList)
 
@@ -58,5 +77,4 @@ function RandomSampler:Refill()
 	self._shuffledAvailableList = newList
 end
 
-
-return RandomSampler
+return RandomSampler

package/src/Shared/RandomUtils.lua

@@ -1,3 +1,4 @@
+--!strict
 --[=[
 	Utility functions involving random variables. This is quite useful
 	for a variety of game mechanics.
@@ -34,7 +35,7 @@ local RandomUtils = {}
 	@param random Random? -- Optional
 	@return T?
 ]=]
-function RandomUtils.choice(list, random)
+function RandomUtils.choice<T>(list: { T }, random: Random?): T?
 	if #list == 0 then
 		return nil
 	elseif #list == 1 then
@@ -63,7 +64,7 @@ end
 	@param random Random? -- Optional random to use when shuffling
 	@return { T }
 ]=]
-function RandomUtils.shuffledCopy(list, random)
+function RandomUtils.shuffledCopy<T>(list: { T }, random: Random?): { T }
 	local copy = table.clone(list)
 
 	RandomUtils.shuffle(copy, random)
@@ -88,7 +89,7 @@ end
 	@param list {T}
 	@param random Random? -- Optional random to use when shuffling
 ]=]
-function RandomUtils.shuffle(list, random)
+function RandomUtils.shuffle<T>(list: { T }, random: Random?)
 	if random then
 		for i = #list, 2, -1 do
 			local j = random:NextInteger(1, i)
@@ -111,6 +112,10 @@ end
 	undefined behavior.
 	:::
 
+	:::tip
+	See [RandomSampler] for a stateful approach where we remove items from the bag.
+	:::
+
 	```lua
 	local weights = { 1, 3, 10 }
 	local options = { "a", "b", "c" }
@@ -123,14 +128,14 @@ end
 	@param random Random? -- Optional random
 	@return T? -- May return nil if the list is empty
 ]=]
-function RandomUtils.weightedChoice(list, weights, random)
+function RandomUtils.weightedChoice<T>(list: { T }, weights: { number }, random: Random): T?
 	if #list == 0 then
 		return nil
 	elseif #list == 1 then
 		return list[1]
 	else
 		local total = 0
-		for i=1, #list do
+		for i = 1, #list do
 			assert(type(weights[i]) == "number", "Bad weights")
 			total = total + weights[i]
 		end
@@ -144,12 +149,12 @@ function RandomUtils.weightedChoice(list, weights, random)
 
 		local totalSum = 0
 
-		for i=1, #list do
+		for i = 1, #list do
 			if weights[i] == 0 then
 				continue
 			end
 			totalSum = totalSum + weights[i]
-			local threshold = totalSum/total
+			local threshold = totalSum / total
 			if randomNum <= threshold then
 				return list[i]
 			end
@@ -167,28 +172,29 @@ end
 	@param random Random? -- Optional random to use
 	@return number
 ]=]
-function RandomUtils.gaussianRandom(random)
+function RandomUtils.gaussianRandom(random: Random?): number
 	local a, t
 	if random then
-		a = 2*math.pi*random:NextNumber()
+		a = 2 * math.pi * random:NextNumber()
 		t = random:NextNumber()
 	else
-		a = 2*math.pi*math.random()
+		a = 2 * math.pi * math.random()
 		t = math.random()
 	end
 
-	return math.sqrt(-2*math.log(1 - t))*math.cos(a)
+	return math.sqrt(-2 * math.log(1 - t)) * math.cos(a)
 end
 
 --[=[
 	@param random? Random? -- Optional random to use
 	@return Vector3
 ]=]
-function RandomUtils.randomUnitVector3(random)
+function RandomUtils.randomUnitVector3(random: Random?): Vector3
 	return Vector3.new(
 		RandomUtils.gaussianRandom(random),
 		RandomUtils.gaussianRandom(random),
-		RandomUtils.gaussianRandom(random))
+		RandomUtils.gaussianRandom(random)
+	)
 end
 
 return RandomUtils

package/src/Shared/WeightedRandomChooser.lua

@@ -57,7 +57,7 @@ end
 	@param option T
 	@return number | nil
 ]=]
-function WeightedRandomChooser:GetWeight(option)
+function WeightedRandomChooser:GetWeight(option): number?
 	return self._optionToWeight[option]
 end
 
@@ -67,14 +67,14 @@ end
 	@param option T
 	@return number | nil
 ]=]
-function WeightedRandomChooser:GetProbability(option)
+function WeightedRandomChooser:GetProbability(option): number?
 	local weight = self._optionToWeight[option]
 	if weight then
 		return nil
 	end
 
 	local cache = self:_getOrCreateDataCache()
-	return weight/cache.total
+	return weight / cache.total
 end
 
 --[=[
@@ -83,7 +83,7 @@ end
 	@param random Random
 	@return T
 ]=]
-function WeightedRandomChooser:Choose(random)
+function WeightedRandomChooser:Choose(random: Random?)
 	local data = self:_getOrCreateDataCache()
 
 	local randomNum
@@ -96,11 +96,11 @@ function WeightedRandomChooser:Choose(random)
 	local totalSum = 0
 
 	-- TODO: Binary search
-	for i=1, #data.options do
+	for i = 1, #data.options do
 		totalSum = totalSum + data.weights[i]
 
 		-- TODO: cache threshold?
-		local threshold = totalSum/data.total
+		local threshold = totalSum / data.total
 		if randomNum <= threshold then
 			return data.options[i]
 		end
@@ -126,11 +126,11 @@ function WeightedRandomChooser:_getOrCreateDataCache()
 	end
 
 	self._cache = {
-		options = options;
-		weights = weights;
-		total = total;
+		options = options,
+		weights = weights,
+		total = total,
 	}
 	return self._cache
 end
 
-return WeightedRandomChooser
+return WeightedRandomChooser