@quenty/metricutils 2.4.3 → 2.5.0

package/src/Shared/MetricUnit.spec.lua

@@ -0,0 +1,362 @@
+--!strict
+--[[
+	@class MetricUnit.spec.lua
+]]
+
+local require = require(script.Parent.loader).load(script)
+
+local Jest = require("Jest")
+local MetricUnit = require("MetricUnit")
+
+local DAY = MetricUnit.days(1):InSeconds()
+local MONTH = MetricUnit.months(1):InSeconds()
+local YEAR = MetricUnit.years(1):InSeconds()
+
+local describe = Jest.Globals.describe
+local expect = Jest.Globals.expect
+local it = Jest.Globals.it
+
+type MetricUnit = MetricUnit.MetricUnit
+
+local DAYS_A_YEAR = YEAR / DAY
+
+describe("MetricUnit constructors and readers", function()
+	it("reads every time unit back", function()
+		expect(MetricUnit.seconds(90):InSeconds()).toBeCloseTo(90, 9)
+		expect(MetricUnit.minutes(90):In("minute")).toBeCloseTo(90, 9)
+		expect(MetricUnit.hours(36):In("hour")).toBeCloseTo(36, 9)
+		expect(MetricUnit.days(3):In("day")).toBe(3)
+		expect(MetricUnit.weeks(2):In("week")).toBe(2)
+		expect(MetricUnit.months(18):In("month")).toBeCloseTo(18, 9)
+		expect(MetricUnit.years(2):In("year")).toBe(2)
+	end)
+
+	it("counts a year and a month by their definitions", function()
+		expect(MetricUnit.hours(36):In("day")).toBeCloseTo(1.5, 9)
+		expect(MetricUnit.seconds(86_400):In("day")).toBeCloseTo(1, 9)
+		expect(MetricUnit.minutes(60):In("hour")).toBeCloseTo(1, 9)
+		expect(MetricUnit.weeks(1):In("day")).toBe(7)
+		expect(MetricUnit.years(1):In("day")).toBe(DAYS_A_YEAR)
+		expect(MetricUnit.months(12):In("year")).toBeCloseTo(1, 9)
+	end)
+
+	it("makes twelve averaged months exactly one averaged year", function()
+		expect(MetricUnit.months(12) == MetricUnit.years(1)).toBe(true)
+		expect(MetricUnit.years(1) / 12 == MetricUnit.months(1)).toBe(true)
+		expect(MONTH * 12).toBe(YEAR)
+	end)
+
+	it("reads every length unit back", function()
+		expect(MetricUnit.millimeters(5):In("millimeter")).toBeCloseTo(5, 9)
+		expect(MetricUnit.new(5, "centimeter"):In("centimeter")).toBeCloseTo(5, 9)
+		expect(MetricUnit.meters(500):In("meter")).toBeCloseTo(500, 9)
+		expect(MetricUnit.kilometers(2):In("kilometer")).toBe(2)
+		expect(MetricUnit.meters(500):In("kilometer")).toBeCloseTo(0.5, 9)
+		expect(MetricUnit.new(100, "centimeter"):In("meter")).toBeCloseTo(1, 9)
+		expect(MetricUnit.millimeters(10):In("centimeter")).toBeCloseTo(1, 9)
+	end)
+
+	it("reads every memory unit back, a kilobyte being 1,000 bytes", function()
+		expect(MetricUnit.bytes(512):In("byte")).toBe(512)
+		expect(MetricUnit.kilobytes(1_600):In("kilobyte")).toBe(1_600)
+		expect(MetricUnit.megabytes(1.6):In("megabyte")).toBeCloseTo(1.6, 9)
+		expect(MetricUnit.kilobytes(1_600):In("megabyte")).toBeCloseTo(1.6, 9)
+		expect(MetricUnit.kilobytes(1):In("byte")).toBe(1_000)
+	end)
+
+	it("reads every mass unit back", function()
+		expect(MetricUnit.grams(250):In("gram")).toBeCloseTo(250, 9)
+		expect(MetricUnit.kilograms(3):In("kilogram")).toBe(3)
+		expect(MetricUnit.tonnes(2):In("tonne")).toBe(2)
+		expect(MetricUnit.tonnes(2):In("kilogram")).toBe(2_000)
+		expect(MetricUnit.grams(500):In("kilogram")).toBeCloseTo(0.5, 9)
+	end)
+
+	it("reads every rate back", function()
+		expect(MetricUnit.perSecond(2):In("perSecond")).toBeCloseTo(2, 9)
+		expect(MetricUnit.perHour(2):In("perHour")).toBeCloseTo(2, 9)
+		expect(MetricUnit.perDay(2):In("perDay")).toBe(2)
+		expect(MetricUnit.new(2, "perWeek"):In("perWeek")).toBeCloseTo(2, 9)
+		expect(MetricUnit.new(2, "perMonth"):In("perMonth")).toBeCloseTo(2, 9)
+		expect(MetricUnit.perYear(0.03):In("perYear")).toBeCloseTo(0.03, 12)
+		expect(MetricUnit.perYear(DAYS_A_YEAR):In("perDay")).toBeCloseTo(1, 9)
+		expect(MetricUnit.perDay(1):In("perHour")).toBeCloseTo(1 / 24, 9)
+	end)
+
+	it("errors when a reader meets another dimension, naming both", function()
+		expect(function()
+			MetricUnit.kilometers(1):In("day")
+		end).toThrow('In("day") reads time, not length')
+		expect(function()
+			MetricUnit.days(1):In("perYear")
+		end).toThrow('In("perYear") reads 1/time, not time')
+		expect(function()
+			(MetricUnit.kilometers(1) / MetricUnit.days(1)):In("kilometer")
+		end).toThrow('In("kilometer") reads length, not length/time')
+		expect(function()
+			MetricUnit.kilograms(1):In("kilobyte")
+		end).toThrow('In("kilobyte") reads memory, not mass')
+	end)
+
+	it("errors when a constructor is given something other than a number", function()
+		expect(function()
+			MetricUnit.kilometers("2" :: any)
+		end).toThrow("MetricUnit.kilometers takes a number, not string")
+	end)
+end)
+
+describe("MetricUnit composition", function()
+	it("reads km a year as km a day", function()
+		local speed = MetricUnit.kilometers(20) / MetricUnit.years(1)
+		expect(speed:In(MetricUnit.kilometers(1) / MetricUnit.days(1))).toBeCloseTo(20 / DAYS_A_YEAR, 12)
+		expect(MetricUnit.isKind(speed, "speed")).toBe(true)
+	end)
+
+	it("reads a speed in km/h with In", function()
+		local speed = MetricUnit.meters(10) / MetricUnit.seconds(1)
+		expect(speed:In(MetricUnit.kilometers(1) / MetricUnit.hours(1))).toBeCloseTo(36, 9)
+	end)
+
+	it("errors when In meets another dimension", function()
+		expect(function()
+			MetricUnit.kilometers(1):In(MetricUnit.days(1))
+		end).toThrow("In cannot read length in time")
+	end)
+
+	it("cancels to dimensionless and reads it with In", function()
+		local ratio = MetricUnit.kilometers(3) / MetricUnit.meters(1_500)
+		expect(ratio:In(MetricUnit.none(1))).toBeCloseTo(2, 9)
+		expect(MetricUnit.sameDimension(ratio, MetricUnit.none(1))).toBe(true)
+	end)
+
+	it("makes a rate from a number over a time", function()
+		local rate = 0.06 / MetricUnit.years(1)
+		expect(MetricUnit.isKind(rate, "rate")).toBe(true)
+		expect(rate:In("perYear")).toBeCloseTo(0.06, 12)
+		expect(MetricUnit.fuzzyEq(rate, MetricUnit.perYear(0.06))).toBe(true)
+	end)
+
+	it("multiplies a rate by a time to a dimensionless count", function()
+		local count = MetricUnit.perDay(3) * MetricUnit.weeks(1)
+		expect(count:In(MetricUnit.none(1))).toBeCloseTo(21, 9)
+	end)
+end)
+
+describe("MetricUnit operators", function()
+	it("scales by a number on either side", function()
+		expect((MetricUnit.years(1) / 4):In("day")).toBeCloseTo(DAYS_A_YEAR / 4, 9)
+		expect((2 * MetricUnit.kilometers(3)):In("kilometer")).toBe(6)
+		expect((MetricUnit.kilometers(3) * 2):In("kilometer")).toBe(6)
+	end)
+
+	it("inverts a unit divided into a number", function()
+		local rate = 2 / MetricUnit.days(4)
+		expect(rate:In("perDay")).toBeCloseTo(0.5, 9)
+	end)
+
+	it("adds and subtracts one dimension", function()
+		expect((MetricUnit.kilometers(1) + MetricUnit.meters(500)):In("meter")).toBeCloseTo(1_500, 9)
+		expect((MetricUnit.years(1) - MetricUnit.days(0.25)):In("day")).toBeCloseTo(DAYS_A_YEAR - 0.25, 9)
+	end)
+
+	it("errors adding or subtracting different dimensions, naming both", function()
+		expect(function()
+			local _ = MetricUnit.kilometers(1) + MetricUnit.days(1)
+		end).toThrow("cannot add length and time")
+		expect(function()
+			local _ = MetricUnit.kilometers(1) - MetricUnit.perDay(1)
+		end).toThrow("cannot subtract length and 1/time")
+	end)
+
+	it("errors adding a plain number other than 0 to a dimensioned unit", function()
+		expect(function()
+			local _ = MetricUnit.kilometers(1) + 2
+		end).toThrow("cannot add length and the plain number 2")
+	end)
+
+	it("adds a plain number to a dimensionless unit", function()
+		expect((MetricUnit.none(1) + 2):In(MetricUnit.none(1))).toBe(3)
+	end)
+
+	it("takes a literal 0 as zero of the other side", function()
+		local function growth(x: boolean): MetricUnit | number
+			return if x then MetricUnit.perYear(0.05) else 0
+		end
+		expect((MetricUnit.perYear(0.01) + growth(false)):In("perYear")).toBeCloseTo(0.01, 12)
+		expect((growth(false) + MetricUnit.perYear(0.01)):In("perYear")).toBeCloseTo(0.01, 12)
+		expect((MetricUnit.kilometers(2) - 0):In("kilometer")).toBe(2)
+		expect((0 - MetricUnit.kilometers(2)):In("kilometer")).toBe(-2)
+	end)
+
+	it("negates", function()
+		expect((-MetricUnit.kilometers(2)):In("kilometer")).toBe(-2)
+	end)
+
+	it("compares one dimension", function()
+		expect(MetricUnit.kilometers(1) < MetricUnit.meters(1_500)).toBe(true)
+		expect(MetricUnit.kilometers(1) <= MetricUnit.meters(1_000)).toBe(true)
+		expect(MetricUnit.kilometers(2) > MetricUnit.meters(1_500)).toBe(true)
+		expect(MetricUnit.hours(24) == MetricUnit.days(1)).toBe(true)
+		expect(MetricUnit.hours(23) == MetricUnit.days(1)).toBe(false)
+	end)
+
+	it("errors comparing different dimensions, naming both", function()
+		expect(function()
+			local _ = MetricUnit.kilometers(1) < MetricUnit.days(1)
+		end).toThrow("cannot compare length and time")
+		expect(function()
+			local _ = MetricUnit.kilometers(1) <= MetricUnit.kilograms(1)
+		end).toThrow("cannot compare length and mass")
+		expect(function()
+			local _ = MetricUnit.kilometers(1) == MetricUnit.days(1)
+		end).toThrow("cannot compare length and time")
+	end)
+
+	it("is frozen, every operation giving a new value", function()
+		local a = MetricUnit.kilometers(1)
+		local b = a + MetricUnit.kilometers(1)
+		expect(table.isfrozen(a :: any)).toBe(true)
+		expect(table.isfrozen(b :: any)).toBe(true)
+		expect(a:In("kilometer")).toBe(1)
+		expect(function()
+			(a :: any)._amount = 5
+		end).toThrow()
+	end)
+end)
+
+describe("MetricUnit helpers", function()
+	it("takes the min, max and clamp of one dimension, a literal 0 among them", function()
+		expect(MetricUnit.min(MetricUnit.kilometers(2), MetricUnit.meters(500)):In("meter")).toBeCloseTo(500, 9)
+		expect(
+			MetricUnit.max(MetricUnit.kilometers(2), MetricUnit.meters(500), MetricUnit.kilometers(3)):In("kilometer")
+		).toBe(3)
+		expect(MetricUnit.max(0, MetricUnit.kilometers(-2)):In("kilometer")).toBe(0)
+		expect(MetricUnit.min(0, MetricUnit.kilometers(2)):In("kilometer")).toBe(0)
+		expect(MetricUnit.clamp(MetricUnit.kilometers(5), 0, MetricUnit.kilometers(3)):In("kilometer")).toBe(3)
+		expect(MetricUnit.clamp(MetricUnit.kilometers(-5), 0, MetricUnit.kilometers(3)):In("kilometer")).toBe(0)
+	end)
+
+	it("errors taking the min of different dimensions", function()
+		expect(function()
+			MetricUnit.min(MetricUnit.kilometers(1), MetricUnit.days(1))
+		end).toThrow("cannot compare")
+	end)
+
+	it("takes the absolute value", function()
+		expect(MetricUnit.abs(MetricUnit.kilometers(-2)):In("kilometer")).toBe(2)
+	end)
+
+	it("takes the square root, halving exponents", function()
+		local area = MetricUnit.kilometers(3) * MetricUnit.kilometers(3)
+		expect(MetricUnit.sqrt(area):In("kilometer")).toBeCloseTo(3, 9)
+		local spread = MetricUnit.kilometers(2) * MetricUnit.kilometers(2) / MetricUnit.days(1)
+		expect(MetricUnit.sqrt(spread * MetricUnit.days(4)):In("kilometer")).toBeCloseTo(4, 9)
+	end)
+
+	it("errors taking the square root of an odd exponent", function()
+		expect(function()
+			MetricUnit.sqrt(MetricUnit.kilometers(4))
+		end).toThrow("length to the power 0.5 has a fractional exponent")
+	end)
+
+	it("raises to a whole power", function()
+		local volume = MetricUnit.pow(MetricUnit.meters(2), 3)
+		expect(volume:In(MetricUnit.pow(MetricUnit.meters(1), 3))).toBeCloseTo(8, 9)
+		expect(MetricUnit.pow(MetricUnit.days(2), -1):In("perDay")).toBeCloseTo(0.5, 9)
+		expect(MetricUnit.pow(MetricUnit.days(2), 0):In(MetricUnit.none(1))).toBe(1)
+		expect(function()
+			MetricUnit.pow(MetricUnit.days(2), 0.5)
+		end).toThrow("whole power")
+	end)
+
+	it("tells units, zeros, signs and dimensions apart", function()
+		expect(MetricUnit.isUnit(MetricUnit.kilometers(1))).toBe(true)
+		expect(MetricUnit.isUnit(1)).toBe(false)
+		expect(MetricUnit.isUnit({})).toBe(false)
+		expect(MetricUnit.isZero(MetricUnit.kilometers(0))).toBe(true)
+		expect(MetricUnit.isZero(0)).toBe(true)
+		expect(MetricUnit.isZero(MetricUnit.kilometers(1))).toBe(false)
+		expect(MetricUnit.sign(MetricUnit.kilometers(-3))).toBe(-1)
+		expect(MetricUnit.sign(MetricUnit.kilometers(0))).toBe(0)
+		expect(MetricUnit.sameDimension(MetricUnit.kilometers(1), MetricUnit.meters(1))).toBe(true)
+		expect(MetricUnit.sameDimension(MetricUnit.kilometers(1), MetricUnit.days(1))).toBe(false)
+		expect(MetricUnit.sameDimension(MetricUnit.kilometers(1), 0)).toBe(true)
+		expect(MetricUnit.sameDimension(MetricUnit.kilometers(1), 2)).toBe(false)
+	end)
+
+	it("compares within a tolerance", function()
+		expect(MetricUnit.fuzzyEq(MetricUnit.hours(24), MetricUnit.days(1))).toBe(true)
+		expect(MetricUnit.fuzzyEq(MetricUnit.kilometers(1), MetricUnit.meters(1_001))).toBe(false)
+		expect(MetricUnit.fuzzyEq(MetricUnit.kilometers(1), MetricUnit.meters(1_001), MetricUnit.meters(2))).toBe(true)
+		expect(function()
+			MetricUnit.fuzzyEq(MetricUnit.kilometers(1), MetricUnit.days(1))
+		end).toThrow("cannot compare length and time")
+	end)
+
+	it("checks dimensions for API boundaries", function()
+		expect(MetricUnit.isKind(MetricUnit.days(1), "time")).toBe(true)
+		expect(MetricUnit.isKind(MetricUnit.kilometers(1), "time")).toBe(false)
+		expect(MetricUnit.isKind(1, "time")).toBe(false)
+		expect(MetricUnit.isKind(MetricUnit.kilometers(1), "length")).toBe(true)
+		expect(MetricUnit.isKind(MetricUnit.perYear(1), "rate")).toBe(true)
+		expect(MetricUnit.isKind(MetricUnit.kilometers(1) / MetricUnit.days(1), "speed")).toBe(true)
+		expect(MetricUnit.isKind(MetricUnit.perYear(1), "speed")).toBe(false)
+		expect(MetricUnit.isKind(MetricUnit.kilobytes(1), "memory")).toBe(true)
+		expect(MetricUnit.isKind(MetricUnit.kilograms(1), "mass")).toBe(true)
+	end)
+end)
+
+describe("MetricUnit.expect", function()
+	it("returns the amount in SI base units", function()
+		expect(MetricUnit.expect(MetricUnit.kilometers(0.5), "length", "reach")).toBe(500)
+		expect(MetricUnit.expect(MetricUnit.years(1), "time", "every")).toBe(YEAR)
+		expect(MetricUnit.expect(MetricUnit.new(60, "perMinute"), "rate", "rate")).toBeCloseTo(1, 9)
+		expect(MetricUnit.expect(MetricUnit.kilometers(36) / MetricUnit.hours(1), "speed", "speed")).toBeCloseTo(10, 9)
+		expect(MetricUnit.expect(MetricUnit.kilobytes(2), "memory", "memory")).toBe(2_000)
+		expect(MetricUnit.expect(MetricUnit.kilometers(1) * MetricUnit.kilometers(1), { length = 2 }, "area")).toBe(1e6)
+	end)
+
+	it("takes a literal 0 as zero of any dimension", function()
+		expect(MetricUnit.expect(0, "length", "reach")).toBe(0)
+		expect(MetricUnit.expect(0, "rate", "rate")).toBe(0)
+	end)
+
+	it("names the slot, the dimension expected and what was given", function()
+		expect(function()
+			MetricUnit.expect(MetricUnit.days(1), "length", "reach")
+		end).toThrow("MetricUnit.expect: reach expects length, got time")
+		expect(function()
+			MetricUnit.expect(2, "rate", "rate")
+		end).toThrow("MetricUnit.expect: rate expects 1/time, got the plain number 2")
+		expect(function()
+			MetricUnit.expect("far" :: any, "length", "reach")
+		end).toThrow("MetricUnit.expect: reach expects length, got string")
+		expect(function()
+			MetricUnit.expect(MetricUnit.kilometers(1), "speed", "speed")
+		end).toThrow("speed expects length/time, got length")
+	end)
+
+	it("errors on an unknown dimension name", function()
+		expect(function()
+			MetricUnit.expect(MetricUnit.kilometers(1), "distance" :: any, "reach")
+		end).toThrow('no kind named "distance"')
+	end)
+end)
+
+describe("MetricUnit data", function()
+	it("round trips through plain data", function()
+		local speed = MetricUnit.kilometers(20) / MetricUnit.years(1)
+		local data = MetricUnit.toData(speed)
+		expect(data).toEqual({ amount = 20_000 / YEAR, dimensions = { length = 1, time = -1 } })
+		expect(table.isfrozen(data)).toBe(false)
+		local back = MetricUnit.fromData(data)
+		expect(back == speed).toBe(true)
+		expect(MetricUnit.isKind(back, "speed")).toBe(true)
+	end)
+
+	it("errors on data that is not a unit", function()
+		expect(function()
+			MetricUnit.fromData({ amount = 1, dimensions = { length = 0.5 } })
+		end).toThrow("MetricUnit.fromData takes")
+	end)
+end)

package/src/Shared/MetricUtils.lua

@@ -1,15 +1,47 @@
 --!strict
 --[=[
-	Provides ways to convert studs to metric and back.
+	Provides ways to convert studs to metric and back, at 3.57 studs to the metre as these functions have always
+	counted them. Each is a plain multiplication, by a factor [MetricUnit] works out once, so they are cheap enough
+	to call every frame; for typed values, or Roblox's own 28 cm stud, use [MetricUnit] directly.
 	@class MetricUtils
 ]=]
 
+local require = require(script.Parent.loader).load(script)
+
+local MetricUnit = require("MetricUnit")
+local MetricUnitSystems = require("MetricUnitSystems")
+
 local MetricUtils = {}
 
-local STUDS_PER_METER = 3.57
-local SECONDS_PER_HOUR = 3600
-local SPEED_OF_SOUND_IN_METERS_PER_SECOND = 343
-local KPH_TO_MPH = 0.621371192
+type Factors = {
+	secondsOfSoundPerStud: number,
+	kilometersPerStud: number,
+	metersPerStud: number,
+	kphPerStudPerSecond: number,
+	mphPerStudPerSecond: number,
+}
+
+local factors: Factors? = nil
+
+local function getFactors(): Factors
+	local found = factors
+	if found then
+		return found
+	end
+	local studs = MetricUnitSystems.roblox({ name = "metricUtils", metersPerStud = 1 / 3.57 })
+	local stud = studs:New(1, "stud")
+	local studPerSecond = studs:New(1, "studPerSecond")
+	local speedOfSoundInDryAirAt20C = MetricUnit.new(343, "meterPerSecond")
+	local computed: Factors = table.freeze({
+		secondsOfSoundPerStud = (stud / speedOfSoundInDryAirAt20C):InSeconds(),
+		kilometersPerStud = stud:In("kilometer"),
+		metersPerStud = stud:In("meter"),
+		kphPerStudPerSecond = studPerSecond:In("kilometerPerHour"),
+		mphPerStudPerSecond = studPerSecond:In("milePerHour"),
+	})
+	factors = computed
+	return computed
+end
 
 --[=[
 	Computes sound delay for the given studs
@@ -17,8 +49,7 @@ local KPH_TO_MPH = 0.621371192
 	@return number -- seconds
 ]=]
 function MetricUtils.getSoundDelaySeconds(studs: number): number
-	local meters = MetricUtils.studsToMeters(studs)
-	return meters / SPEED_OF_SOUND_IN_METERS_PER_SECOND
+	return studs * getFactors().secondsOfSoundPerStud
 end
 
 --[=[
@@ -27,7 +58,7 @@ end
 	@return number -- kilometers
 ]=]
 function MetricUtils.studsToKilometers(studs: number): number
-	return studs / STUDS_PER_METER / 1000
+	return studs * getFactors().kilometersPerStud
 end
 
 --[=[
@@ -36,7 +67,7 @@ end
 	@return number -- meters
 ]=]
 function MetricUtils.studsToMeters(studs: number): number
-	return studs / STUDS_PER_METER
+	return studs * getFactors().metersPerStud
 end
 
 --[=[
@@ -45,17 +76,17 @@ end
 	@return number -- kph
 ]=]
 function MetricUtils.studsPerSecondToKph(studsPerSecond: number): number
-	return studsPerSecond / STUDS_PER_METER / 1000 * SECONDS_PER_HOUR
+	return studsPerSecond * getFactors().kphPerStudPerSecond
 end
 
 --[=[
 	Convert from studs per a second to meters per a second
 
 	@param studsPerSecond number
-	@return number -- kph
+	@return number -- meters per a second
 ]=]
 function MetricUtils.studsPerSecondToMetersPerSecond(studsPerSecond: number): number
-	return studsPerSecond / STUDS_PER_METER
+	return studsPerSecond * getFactors().metersPerStud
 end
 
 --[=[
@@ -64,16 +95,16 @@ end
 	@return number -- mph
 ]=]
 function MetricUtils.studsPerSecondToMph(studsPerSecond: number): number
-	return studsPerSecond / STUDS_PER_METER / 1000 * SECONDS_PER_HOUR * KPH_TO_MPH
+	return studsPerSecond * getFactors().mphPerStudPerSecond
 end
 
 --[=[
-	Convert mph to studs per a second
+	Convert kph to studs per a second
 	@param kph number
 	@return number -- studs per a second
 ]=]
 function MetricUtils.kphToStudsPerSecond(kph: number): number
-	return kph * STUDS_PER_METER * 1000 / SECONDS_PER_HOUR
+	return kph / getFactors().kphPerStudPerSecond
 end
 
 --[=[
@@ -82,7 +113,7 @@ end
 	@return number  -- studs per a second
 ]=]
 function MetricUtils.mphToStudsPerSecond(mph: number): number
-	return mph * STUDS_PER_METER * 1000 / SECONDS_PER_HOUR / KPH_TO_MPH
+	return mph / getFactors().mphPerStudPerSecond
 end
 
 return MetricUtils

package/src/Shared/MetricUtils.spec.lua

@@ -0,0 +1,76 @@
+--!strict
+--[[
+	@class MetricUtils.spec.lua
+]]
+
+local require = require(script.Parent.loader).load(script)
+
+local Jest = require("Jest")
+local MetricUtils = require("MetricUtils")
+
+local describe = Jest.Globals.describe
+local expect = Jest.Globals.expect
+local it = Jest.Globals.it
+
+describe("MetricUtils.getSoundDelaySeconds", function()
+	it("takes one second for sound to cross 343 meters", function()
+		expect(MetricUtils.getSoundDelaySeconds(343 * 3.57)).toBeCloseTo(1, 9)
+	end)
+
+	it("is zero at zero distance", function()
+		expect(MetricUtils.getSoundDelaySeconds(0)).toBe(0)
+	end)
+end)
+
+describe("MetricUtils.studsToMeters", function()
+	it("converts at 3.57 studs per meter", function()
+		expect(MetricUtils.studsToMeters(357)).toBeCloseTo(100, 9)
+		expect(MetricUtils.studsToMeters(-3.57)).toBeCloseTo(-1, 9)
+		expect(MetricUtils.studsToMeters(0)).toBe(0)
+	end)
+end)
+
+describe("MetricUtils.studsToKilometers", function()
+	it("converts studs to kilometers", function()
+		expect(MetricUtils.studsToKilometers(3570)).toBeCloseTo(1, 9)
+		expect(MetricUtils.studsToKilometers(0)).toBe(0)
+	end)
+end)
+
+describe("MetricUtils.studsPerSecondToMetersPerSecond", function()
+	it("converts a stud velocity to meters per second", function()
+		expect(MetricUtils.studsPerSecondToMetersPerSecond(35.7)).toBeCloseTo(10, 9)
+	end)
+end)
+
+describe("MetricUtils.studsPerSecondToKph", function()
+	it("converts a stud velocity to kilometers per hour", function()
+		expect(MetricUtils.studsPerSecondToKph(3.57)).toBeCloseTo(3.6, 9)
+	end)
+end)
+
+describe("MetricUtils.studsPerSecondToMph", function()
+	it("converts a stud velocity to miles per hour", function()
+		expect(MetricUtils.studsPerSecondToMph(3.57 * 0.44704)).toBeCloseTo(1, 9)
+	end)
+end)
+
+describe("MetricUtils.kphToStudsPerSecond", function()
+	it("converts kilometers per hour to a stud velocity", function()
+		expect(MetricUtils.kphToStudsPerSecond(3.6)).toBeCloseTo(3.57, 9)
+	end)
+
+	it("inverts studsPerSecondToKph", function()
+		expect(MetricUtils.kphToStudsPerSecond(MetricUtils.studsPerSecondToKph(16))).toBeCloseTo(16, 9)
+	end)
+end)
+
+describe("MetricUtils.mphToStudsPerSecond", function()
+	it("converts miles per hour to a stud velocity", function()
+		expect(MetricUtils.mphToStudsPerSecond(1)).toBeCloseTo(3.57 * 0.44704, 9)
+	end)
+
+	it("inverts studsPerSecondToMph", function()
+		expect(MetricUtils.mphToStudsPerSecond(MetricUtils.studsPerSecondToMph(16))).toBeCloseTo(16, 9)
+	end)
+end)