@quenty/metricutils 2.4.3 → 2.5.0

package/src/Shared/MetricUnit.Display.spec.lua

@@ -0,0 +1,153 @@
+--!strict
+--[[
+	@class MetricUnit.Display.spec.lua
+]]
+
+local require = require(script.Parent.loader).load(script)
+
+local Jest = require("Jest")
+local MetricUnit = require("MetricUnit")
+
+local describe = Jest.Globals.describe
+local expect = Jest.Globals.expect
+local it = Jest.Globals.it
+
+local function preferenceOf(value: MetricUnit.MetricUnit): string?
+	local system = value:GetDisplaySystem()
+	local unit = value:GetDisplayUnit()
+	return if unit then unit.id elseif system then system:GetName() else nil
+end
+
+-- Formatting puts a no-break space between a number and its unit; these compare it as a plain space
+local function plain(text: string): string
+	return (string.gsub(text, "\u{00A0}", " "))
+end
+
+local function format(value: any, options: MetricUnit.FormatOptions?): string
+	return plain(MetricUnit.format(value, options))
+end
+
+local function mismatches(cases: { { any } }): { string }
+	local found = {}
+	for _, case in cases do
+		local text = string.gsub(tostring(case[1]), "\u{00A0}", " ")
+		if text ~= case[2] then
+			table.insert(found, string.format("expected %q, got %q", case[2], text))
+		end
+	end
+	return found
+end
+
+describe("MetricUnit display preference", function()
+	it("prefers imperial units or a pinned unit only when asked", function()
+		local distance = MetricUnit.kilometers(5)
+		expect(format(distance)).toBe("5 km")
+		expect(format(distance:ToUSCustomary())).toBe("3.107 mi")
+		expect(format(distance:As("mile"))).toBe("3.107 mi")
+		expect(format(distance:As("meter"))).toBe("5,000 m")
+		expect(format(MetricUnit.meters(28):As("stud"))).toBe("100 studs")
+		expect(format(distance:ToUSCustomary():ToMetric())).toBe("5 km")
+		expect(preferenceOf(distance:ToUSCustomary())).toBe("usCustomary")
+		expect(preferenceOf(distance)).toBeNil()
+	end)
+
+	it("never takes a measurement system from the locale", function()
+		local distance = MetricUnit.kilometers(5)
+		expect(format(distance, { locale = "en-us" })).toBe("5 km")
+		expect(format(distance, { locale = "en-us", unitDisplay = "long" })).toBe("5 kilometers")
+		expect(format(MetricUnit.celsius(20), { locale = "en-us" })).toBe("20 °C")
+	end)
+
+	it("lets an explicit unit option win over the preference", function()
+		expect(format(MetricUnit.kilometers(5):ToUSCustomary(), { unit = "meter" })).toBe("5,000 m")
+	end)
+
+	it("errors pinning a unit of another dimension", function()
+		expect(function()
+			MetricUnit.kilometers(5):As("kilogram")
+		end).toThrow('MetricUnit:As("kilogram") is mass, not length')
+	end)
+
+	it("never changes the amount, comparison, reading or saved data", function()
+		local distance = MetricUnit.kilometers(5)
+		local imperial = distance:ToUSCustomary()
+		expect(imperial == distance).toBe(true)
+		expect(imperial:In("kilometer")).toBe(5)
+		expect(MetricUnit.expect(imperial, "length", "reach")).toBe(5000)
+		expect(MetricUnit.toData(imperial)).toEqual({ amount = 5000, dimensions = { length = 1 } })
+		expect(preferenceOf(MetricUnit.fromData(MetricUnit.toData(imperial)))).toBeNil()
+	end)
+
+	it("carries through arithmetic of one dimension when the sides agree", function()
+		local imperial = MetricUnit.kilometers(5):ToUSCustomary()
+		expect(preferenceOf((imperial + MetricUnit.kilometers(1)))).toBe("usCustomary")
+		expect(preferenceOf((MetricUnit.kilometers(1) + imperial))).toBe("usCustomary")
+		expect(preferenceOf((imperial + MetricUnit.kilometers(1):ToMetric()))).toBeNil()
+		expect(preferenceOf(MetricUnit.max(imperial, MetricUnit.kilometers(1)))).toBe("usCustomary")
+		expect(preferenceOf(MetricUnit.sum({ imperial, MetricUnit.kilometers(1) }))).toBe("usCustomary")
+		expect(preferenceOf(-imperial)).toBe("usCustomary")
+	end)
+
+	it("keeps a pinned unit through scaling, and its system through a change of dimension", function()
+		local pinned = MetricUnit.kilometers(5):As("mile")
+		expect(preferenceOf((pinned * 2))).toBe("mile")
+		expect(preferenceOf((2 * pinned))).toBe("mile")
+		expect(preferenceOf((pinned / 2))).toBe("mile")
+		expect(preferenceOf((pinned + MetricUnit.kilometers(1)))).toBe("mile")
+		expect(preferenceOf(pinned / MetricUnit.hours(1))).toBe("usCustomaryAndImperial")
+		expect(format(MetricUnit.kilometers(5):ToUSCustomary() / MetricUnit.hours(1))).toBe("3.107 mph")
+		-- A stud's system shows studs per second for the speed it makes
+		expect(preferenceOf(MetricUnit.meters(1):As("stud") / MetricUnit.seconds(1))).toBe("roblox")
+	end)
+end)
+
+describe("MetricUnit tostring", function()
+	it("is the English short format with four significant digits", function()
+		expect(mismatches({
+			{ MetricUnit.days(3.5), "3 days, 12 hours" },
+			{ MetricUnit.years(2), "2 years" },
+			{ MetricUnit.minutes(90), "1 hour, 30 minutes" },
+			{ MetricUnit.seconds(30), "30 seconds" },
+			{ MetricUnit.kilometers(2), "2 km" },
+			{ MetricUnit.meters(500), "500 m" },
+			{ MetricUnit.millimeters(4), "4 mm" },
+			{ MetricUnit.kilobytes(1_600), "1.6 MB" },
+			{ MetricUnit.bytes(12), "12 B" },
+			{ MetricUnit.tonnes(3), "3 t" },
+			{ MetricUnit.grams(20), "20 g" },
+			{ MetricUnit.kilometers(0), "0 m" },
+			{ MetricUnit.days(0), "0 seconds" },
+			{ MetricUnit.perYear(0.03), "0.03/yr" },
+			{ MetricUnit.perDay(5), "5/d" },
+			{ MetricUnit.perSecond(2), "2/s" },
+			{ MetricUnit.new(60, "hertz"), "60/s" },
+			{ MetricUnit.kilometers(18) / MetricUnit.hours(1), "5 m/s" },
+			{ MetricUnit.kilometers(20) / MetricUnit.years(1), "2.282 m/h" },
+			{ MetricUnit.new(1_600, "kilobytePerSecond"), "1.6 MB/s" },
+			{ MetricUnit.bytes(20) / MetricUnit.days(1), "20 B/d" },
+			{ MetricUnit.milliseconds(250), "250 milliseconds" },
+			{ MetricUnit.new(40, "microsecond"), "40 microseconds" },
+			{ MetricUnit.kilometers(3) * MetricUnit.kilometers(2), "6 km²" },
+			{ MetricUnit.new(50, "squareMeter"), "50 m²" },
+			{ MetricUnit.new(2.5, "liter"), "2.5 L" },
+			{ MetricUnit.new(3, "cubicMeter"), "3 m³" },
+			{ MetricUnit.new(9.81, "meterPerSecondSquared"), "9.81 m/s²" },
+			{ MetricUnit.new(1_500, "newton"), "1.5 kN" },
+			{ MetricUnit.new(1, "kilowattHour"), "3.6 MJ" },
+			{ MetricUnit.new(2_500, "watt"), "2.5 kW" },
+			{ MetricUnit.new(1, "bar"), "100 kPa" },
+			{ MetricUnit.new(1_000, "kilogramPerCubicMeter"), "1,000 kg/m³" },
+			{ MetricUnit.new(2, "gigabyte"), "2 GB" },
+			{ MetricUnit.new(5, "milligram"), "5 mg" },
+			{ MetricUnit.kilograms(2) / MetricUnit.kilometers(1), "0.002 kg/m" },
+			{ MetricUnit.kilograms(2) * MetricUnit.new(3, "meterPerSecond"), "6 m·kg/s" },
+			{ MetricUnit.none(0.25), "0.25" },
+			{ MetricUnit.years(10_000), "10,000 years" },
+			{ MetricUnit.celsius(5), "5 °C" },
+			{ MetricUnit.celsius(5) - MetricUnit.celsius(2), "3 K" },
+			{ MetricUnit.meters(1 / 3), "33.33 cm" },
+			{ MetricUnit.kilometers(5):ToUSCustomary(), "3.107 mi" },
+			{ MetricUnit.instant(90), "epoch + 1 minute, 30 seconds" },
+		})).toEqual({})
+	end)
+end)

package/src/Shared/MetricUnit.Electrical.spec.lua

@@ -0,0 +1,114 @@
+--!strict
+--[[
+	@class MetricUnit.Electrical.spec.lua
+]]
+
+local require = require(script.Parent.loader).load(script)
+
+local Jest = require("Jest")
+local MetricUnit = require("MetricUnit")
+
+local describe = Jest.Globals.describe
+local expect = Jest.Globals.expect
+local it = Jest.Globals.it
+
+local function format(value: any): string
+	return (string.gsub(MetricUnit.format(value), "\u{00A0}", " "))
+end
+
+local function parse(text: string, kind: any?): MetricUnit.MetricUnit
+	local value, err = MetricUnit.parse(text, kind)
+	if not value then
+		error(string.format("could not parse %q: %s", text, tostring(err)))
+	end
+	return value
+end
+
+describe("MetricUnit circuits", function()
+	it("follows Ohm's law and the power law", function()
+		local voltage = MetricUnit.new(12, "volt")
+		local resistance = MetricUnit.new(4.7, "kilohm")
+		local current = voltage / resistance
+		expect(current:GetKind()).toBe("current")
+		expect(current:In("milliampere")).toBeCloseTo(2.5532, 4)
+		expect((current * resistance):In("volt")).toBeCloseTo(12, 9)
+		expect((voltage * current):GetKind()).toBe("power")
+		expect((voltage * current):In("watt")).toBeCloseTo(0.030638, 6)
+	end)
+
+	it("makes seconds from RC and L/R time constants", function()
+		local tau = MetricUnit.new(10, "kilohm") * MetricUnit.new(100, "nanofarad")
+		expect(tau:GetKind()).toBe("time")
+		expect(tau:In("millisecond")).toBeCloseTo(1, 9)
+		local inductive = MetricUnit.new(10, "millihenry") / MetricUnit.new(1, "ohm")
+		expect(inductive:In("millisecond")).toBeCloseTo(10, 9)
+	end)
+
+	it("relates charge, capacitance and stored energy", function()
+		local capacitance = MetricUnit.new(470, "microfarad")
+		local voltage = MetricUnit.new(5, "volt")
+		local charge = capacitance * voltage
+		expect(charge:GetKind()).toBe("charge")
+		expect(charge:In("coulomb")).toBeCloseTo(0.00235, 9)
+		expect((charge / MetricUnit.seconds(1)):In("milliampere")).toBeCloseTo(2.35, 9)
+		local energy = 0.5 * capacitance * MetricUnit.pow(voltage, 2)
+		expect(energy:In("joule")).toBeCloseTo(0.005875, 9)
+	end)
+
+	it("relates flux, flux density, inductance and conductance", function()
+		local flux = MetricUnit.new(2, "volt") * MetricUnit.seconds(3)
+		expect(flux:GetKind()).toBe("magneticFlux")
+		expect(flux:In("weber")).toBe(6)
+		expect((flux / MetricUnit.new(2, "squareMeter")):In("tesla")).toBe(3)
+		expect((flux / MetricUnit.new(2, "ampere")):In("henry")).toBe(3)
+		expect((1 / MetricUnit.new(50, "ohm")):In("siemens")).toBeCloseTo(0.02, 9)
+	end)
+
+	it("names every electrical kind", function()
+		expect(MetricUnit.new(1, "ampere"):GetKind()).toBe("current")
+		expect(MetricUnit.new(1, "coulomb"):GetKind()).toBe("charge")
+		expect(MetricUnit.new(1, "volt"):GetKind()).toBe("voltage")
+		expect(MetricUnit.new(1, "ohm"):GetKind()).toBe("resistance")
+		expect(MetricUnit.new(1, "siemens"):GetKind()).toBe("conductance")
+		expect(MetricUnit.new(1, "farad"):GetKind()).toBe("capacitance")
+		expect(MetricUnit.new(1, "henry"):GetKind()).toBe("inductance")
+		expect(MetricUnit.new(1, "weber"):GetKind()).toBe("magneticFlux")
+		expect(MetricUnit.new(1, "tesla"):GetKind()).toBe("magneticFluxDensity")
+	end)
+end)
+
+describe("MetricUnit electrical formatting", function()
+	it("picks the prefix a component is labelled with", function()
+		expect(format(MetricUnit.new(4700, "ohm"))).toBe("4.7 kΩ")
+		expect(format(MetricUnit.new(0.1, "microfarad"))).toBe("100 nF")
+		expect(format(MetricUnit.new(0.0015, "ampere"))).toBe("1.5 mA")
+		expect(format(MetricUnit.new(3.3, "volt"))).toBe("3.3 V")
+		expect(format(MetricUnit.new(2200, "microhenry"))).toBe("2.2 mH")
+		expect(format(MetricUnit.new(0.05, "tesla"))).toBe("50 mT")
+		expect(format(MetricUnit.new(2, "volt") / MetricUnit.seconds(1))).toBe("2 V/s")
+	end)
+end)
+
+describe("MetricUnit electrical parsing", function()
+	it("reads component values as they are written", function()
+		expect(parse("4.7kΩ"):In("ohm")).toBeCloseTo(4700, 9)
+		expect(parse("4.7 kilohms"):In("ohm")).toBeCloseTo(4700, 9)
+		expect(parse("100nF"):In("nanofarad")).toBeCloseTo(100, 9)
+		expect(parse("10 uF"):In("microfarad")).toBeCloseTo(10, 9)
+		expect(parse("10 µF"):In("microfarad")).toBeCloseTo(10, 9)
+		expect(parse("12 V"):In("volt")).toBe(12)
+		expect(parse("2 amps"):In("ampere")).toBe(2)
+	end)
+
+	it("reads the Greek mu and the ohm sign as the micro sign and omega", function()
+		expect(parse("10 \u{03BC}F"):In("microfarad")).toBeCloseTo(10, 9)
+		expect(parse("5 \u{2126}"):In("ohm")).toBe(5)
+	end)
+
+	it("keeps C and F as temperatures unless a charge or capacitance is expected", function()
+		expect(parse("20 C"):GetKind()).toBe("temperature")
+		expect(parse("20 F"):GetKind()).toBe("temperature")
+		expect(parse("20 C", "charge"):In("coulomb")).toBe(20)
+		expect(parse("20 F", "capacitance"):In("farad")).toBe(20)
+	end)
+end)

package/src/Shared/MetricUnit.Math.spec.lua

@@ -0,0 +1,112 @@
+--!strict
+--[[
+	@class MetricUnit.Math.spec.lua
+]]
+
+local require = require(script.Parent.loader).load(script)
+
+local Jest = require("Jest")
+local MetricUnit = require("MetricUnit")
+local MetricUnitSystems = require("MetricUnitSystems")
+
+local describe = Jest.Globals.describe
+local expect = Jest.Globals.expect
+local it = Jest.Globals.it
+
+describe("MetricUnit.lerp", function()
+	it("interpolates differences and absolutes alike", function()
+		expect(MetricUnit.lerp(MetricUnit.meters(0), MetricUnit.meters(10), 0.25):In("meter")).toBe(2.5)
+		local temperature = MetricUnit.lerp(MetricUnit.celsius(10), MetricUnit.celsius(20), 0.5)
+		expect(temperature:IsAbsolute()).toBe(true)
+		expect(temperature:In("celsius")).toBeCloseTo(15, 9)
+		local instant = MetricUnit.lerp(MetricUnit.instant(0), MetricUnit.instant(100), 0.5)
+		expect(instant:GetKind()).toBe("instant")
+		expect(instant:InSeconds()).toBe(50)
+	end)
+
+	it("errors between different dimensions", function()
+		expect(function()
+			MetricUnit.lerp(MetricUnit.meters(1), MetricUnit.seconds(1), 0.5)
+		end).toThrow("cannot subtract")
+	end)
+end)
+
+describe("MetricUnit rounding", function()
+	it("rounds, floors and ceils to a unit", function()
+		expect(MetricUnit.round(MetricUnit.seconds(95), "minute"):In("minute")).toBe(2)
+		expect(MetricUnit.floor(MetricUnit.seconds(95), "minute"):In("minute")).toBe(1)
+		expect(MetricUnit.ceil(MetricUnit.seconds(61), "minute"):In("minute")).toBe(2)
+		expect(MetricUnit.round(MetricUnit.meters(1234), "kilometer"):In("kilometer")).toBe(1)
+	end)
+
+	it("snaps to a multiple of a step", function()
+		expect(MetricUnit.round(MetricUnit.meters(12.4), MetricUnit.meters(5)):In("meter")).toBe(10)
+		expect(MetricUnit.round(MetricUnit.meters(12.6), MetricUnit.meters(5)):In("meter")).toBe(15)
+		expect(function()
+			MetricUnit.round(MetricUnit.meters(1), MetricUnit.meters(-5))
+		end).toThrow("takes a positive step of length")
+		expect(function()
+			MetricUnit.round(MetricUnit.meters(1), MetricUnit.seconds(1))
+		end).toThrow("takes a positive step of length, not time")
+	end)
+
+	it("rounds a temperature on its scale and an instant from its epoch", function()
+		local warm = MetricUnit.round(MetricUnit.celsius(21.6), "celsius")
+		expect(warm:IsAbsolute()).toBe(true)
+		expect(warm:In("celsius")).toBeCloseTo(22, 9)
+		local instant = MetricUnit.round(MetricUnit.instant(95), "minute")
+		expect(instant:GetKind()).toBe("instant")
+		expect(instant:InSeconds()).toBe(120)
+	end)
+
+	it("keeps the display preference and errors on an unknown unit", function()
+		expect(MetricUnit.round(MetricUnit.kilometers(1.4):ToUSCustomary(), "mile"):GetDisplaySystem()).toBe(
+			MetricUnitSystems.US_CUSTOMARY
+		)
+		expect(function()
+			MetricUnit.round(MetricUnit.meters(1), "klicks" :: any)
+		end).toThrow('MetricUnit.round knows no unit "klicks"')
+	end)
+end)
+
+describe("MetricUnit aggregation", function()
+	it("sums values of one dimension", function()
+		expect(MetricUnit.sum({ MetricUnit.meters(1), MetricUnit.kilometers(1) }):In("meter")).toBe(1001)
+		expect(MetricUnit.sum({ 1, 2 }):GetBaseAmount()).toBe(3)
+		expect(function()
+			MetricUnit.sum({ MetricUnit.celsius(1), MetricUnit.celsius(2) })
+		end).toThrow("cannot add two absolute temperatures")
+		expect(function()
+			MetricUnit.sum({})
+		end).toThrow("takes a list of at least one value")
+	end)
+
+	it("averages values, absolutes included", function()
+		expect(MetricUnit.mean({ MetricUnit.meters(1), MetricUnit.meters(3) }):In("meter")).toBe(2)
+		local temperature = MetricUnit.mean({ MetricUnit.celsius(10), MetricUnit.celsius(20) })
+		expect(temperature:IsAbsolute()).toBe(true)
+		expect(temperature:In("celsius")).toBeCloseTo(15, 9)
+		expect(MetricUnit.mean({ MetricUnit.instant(10), MetricUnit.instant(20) }):InSeconds()).toBe(15)
+	end)
+
+	it("takes the smallest and largest of a list through min and max", function()
+		local list = { MetricUnit.meters(1), MetricUnit.meters(5), MetricUnit.meters(3) }
+		expect(MetricUnit.max(table.unpack(list)):In("meter")).toBe(5)
+		expect(MetricUnit.min(table.unpack(list)):In("meter")).toBe(1)
+	end)
+end)
+
+describe("MetricUnit rounding an absolute value by a step", function()
+	it("rounds a temperature on the scale it is shown in", function()
+		local step = MetricUnit.difference(5, "celsius")
+		expect(MetricUnit.round(MetricUnit.celsius(21.6), step):In("celsius")).toBeCloseTo(20, 9)
+		expect(MetricUnit.round(MetricUnit.celsius(23), step):In("celsius")).toBeCloseTo(25, 9)
+		local fahrenheitStep = MetricUnit.difference(10, "fahrenheit")
+		expect(MetricUnit.round(MetricUnit.fahrenheit(68), fahrenheitStep):In("fahrenheit")).toBeCloseTo(70, 9)
+	end)
+
+	it("rounds an instant from its epoch", function()
+		local rounded = MetricUnit.round(MetricUnit.instant(95), MetricUnit.minutes(1))
+		expect(rounded:In("second")).toBeCloseTo(120, 9)
+	end)
+end)

package/src/Shared/MetricUnit.Roblox.spec.lua

@@ -0,0 +1,34 @@
+--!strict
+--[[
+	@class MetricUnit.Roblox.spec.lua
+]]
+
+local require = require(script.Parent.loader).load(script)
+
+local Jest = require("Jest")
+local MetricUnit = require("MetricUnit")
+
+local describe = Jest.Globals.describe
+local expect = Jest.Globals.expect
+local it = Jest.Globals.it
+
+describe("MetricUnit and the Roblox engine", function()
+	it("converts Roblox mass units and stud accelerations through the documented stud and RMU", function()
+		-- A Roblox mass unit is a cubic stud of water
+		expect(MetricUnit.new(1, "robloxMassUnit"):In("kilogram")).toBeCloseTo(21.952, 9)
+		expect(MetricUnit.new(196.2, "studPerSecondSquared"):In("meterPerSecondSquared")).toBeCloseTo(196.2 * 0.28, 9)
+		-- An engine force is a mass times an acceleration, so it needs no unit of its own
+		local force = MetricUnit.new(1, "robloxMassUnit") * MetricUnit.new(1, "studPerSecondSquared")
+		expect(force:GetKind()).toBe("force")
+		expect(force:In("newton")).toBeCloseTo(21.952 * 0.28, 9)
+	end)
+
+	it("reads a velocity's speed in studs per second", function()
+		if typeof(Vector3) ~= "table" and typeof(Vector3) ~= "userdata" then
+			return -- Vector3 exists in Roblox only
+		end
+		local speed = MetricUnit.fromStudVelocity(Vector3.new(3, 4, 0))
+		expect(speed:In("studPerSecond")).toBeCloseTo(5, 9)
+		expect(speed:In("meterPerSecond")).toBeCloseTo(5 * 0.28, 9)
+	end)
+end)

package/src/Shared/MetricUnit.SI.spec.lua

@@ -0,0 +1,127 @@
+--!strict
+--[[
+	@class MetricUnit.SI.spec.lua
+]]
+
+local require = require(script.Parent.loader).load(script)
+
+local Jest = require("Jest")
+local MetricUnit = require("MetricUnit")
+local MetricUnitDefinitions = require("MetricUnitDefinitions")
+
+local describe = Jest.Globals.describe
+local expect = Jest.Globals.expect
+local it = Jest.Globals.it
+
+local function format(value: any, options: any?): string
+	return (string.gsub(MetricUnit.format(value, options), "\u{00A0}", " "))
+end
+
+local function parse(text: string, kind: any?): MetricUnit.MetricUnit
+	local value, err = MetricUnit.parse(text, kind)
+	if not value then
+		error(string.format("could not parse %q: %s", text, tostring(err)))
+	end
+	return value
+end
+
+describe("MetricUnit SI prefixes", function()
+	it("makes every SI prefix of a prefixable unit", function()
+		expect(#MetricUnitDefinitions.getPrefixes()).toBe(32)
+		for _, prefix in MetricUnitDefinitions.getPrefixes() do
+			local unit = MetricUnitDefinitions.getUnit(prefix.name .. "volt")
+			local isBinary = string.find(prefix.symbol, "i", 1, true) ~= nil
+			if isBinary then
+				expect(unit).toBeNil()
+			else
+				assert(unit, prefix.name .. "volt")
+				expect(unit.symbol).toBe(prefix.symbol .. "V")
+				expect(unit.factor).toBe(prefix.factor)
+			end
+		end
+		expect(MetricUnit.new(3, "nanometer" :: any):In("meter")).toBeCloseTo(3e-9, 20)
+		expect(MetricUnit.new(1, "quettameter" :: any):In("meter")).toBe(1e30)
+	end)
+
+	it("prefixes the gram, so the kilogram is one SI base unit", function()
+		local kilogram = assert(MetricUnitDefinitions.getUnit("kilogram"))
+		expect(kilogram.factor).toBe(1)
+		expect(kilogram.prefix).toEqual({ name = "kilo", base = "gram" })
+		expect(MetricUnitDefinitions.getUnit("kilokilogram" :: any)).toBeNil()
+		expect(MetricUnit.new(5, "microgram"):In("milligram")).toBeCloseTo(0.005, 12)
+	end)
+
+	it("gives bytes binary prefixes and only multiples", function()
+		expect(MetricUnit.new(1, "mebibyte" :: any):In("byte")).toBe(1024 ^ 2)
+		expect(MetricUnit.new(1, "terabyte"):In("gigabyte")).toBe(1000)
+		expect(MetricUnitDefinitions.getUnit("millibyte" :: any)).toBeNil()
+		expect(MetricUnitDefinitions.getUnit("kibibit" :: any)).toBeNil()
+	end)
+
+	it("names prefixed units in English, eliding the vowel before ohm", function()
+		expect(format(MetricUnit.new(3, "nanometer" :: any), { unit = "nanometer", unitDisplay = "long" })).toBe(
+			"3 nanometers"
+		)
+		expect(format(MetricUnit.new(1, "kilohm"), { unit = "kilohm", unitDisplay = "long" })).toBe("1 kilohm")
+		expect(format(MetricUnit.new(2, "megohm"), { unit = "megohm", unitDisplay = "long" })).toBe("2 megohms")
+		expect(format(MetricUnit.new(2, "millihenry"), { unit = "millihenry", unitDisplay = "long" })).toBe(
+			"2 millihenries"
+		)
+		expect(format(MetricUnit.new(2, "kilometer"), { unit = "kilometer", unitDisplay = "long", locale = "en-gb" })).toBe(
+			"2 kilometres"
+		)
+	end)
+
+	it("parses any prefix by symbol, name, or u for micro", function()
+		expect(parse("5 GHz"):In("hertz")).toBe(5e9)
+		expect(parse("3 nm"):In("nanometer" :: any)).toBeCloseTo(3, 9)
+		expect(parse("2 megawatts"):In("watt")).toBe(2e6)
+		expect(parse("10 us"):In("microsecond")).toBeCloseTo(10, 9)
+		expect(parse("4 uA"):In("microampere")).toBeCloseTo(4, 9)
+		expect(parse("250 ml"):In("liter")).toBeCloseTo(0.25, 9)
+		expect(parse("2 dL"):In("deciliter")).toBeCloseTo(2, 9)
+		expect(parse("3 milliamps"):In("ampere")).toBeCloseTo(0.003, 9)
+		expect(parse("5 M"):GetKind()).toBe("time")
+	end)
+end)
+
+describe("MetricUnit amount of substance and light", function()
+	it("converts mass, moles and concentration", function()
+		local waterMolarMass = MetricUnit.new(18.015, "gramPerMole")
+		local moles = MetricUnit.grams(36.03) / waterMolarMass
+		expect(moles:GetKind()).toBe("amount")
+		expect(moles:In("mole")).toBeCloseTo(2, 9)
+		local concentration = moles / MetricUnit.new(4, "liter")
+		expect(concentration:GetKind()).toBe("molarConcentration")
+		expect(concentration:In("millimolePerLiter")).toBeCloseTo(500, 6)
+		expect((moles / MetricUnit.seconds(2)):In("katal")).toBeCloseTo(1, 9)
+	end)
+
+	it("reads liquid volume from mass through a density", function()
+		local water = MetricUnit.new(1000, "kilogramPerCubicMeter")
+		local volume = MetricUnit.kilograms(2) / water
+		expect(volume:In("liter")).toBeCloseTo(2, 9)
+		expect(format(volume)).toBe("2 L")
+		expect((MetricUnit.new(330, "milliliter") * water):In("gram")).toBeCloseTo(330, 9)
+		expect(MetricUnit.new(1, "usGallon"):In("centiliter")).toBeCloseTo(378.5411784, 6)
+	end)
+
+	it("derives lumens and lux from the candela and the steradian", function()
+		local flux = MetricUnit.new(100, "candela") * MetricUnit.new(2, "steradian")
+		expect(flux:GetKind()).toBe("luminousFlux")
+		expect(flux:In("lumen")).toBe(200)
+		local illuminance = flux / MetricUnit.new(4, "squareMeter")
+		expect(illuminance:GetKind()).toBe("illuminance")
+		expect(illuminance:In("lux")).toBe(50)
+		expect(MetricUnit.pow(MetricUnit.radians(1), 2):In("steradian")).toBe(1)
+	end)
+
+	it("shares dimensions where SI does, showing the first unit unless asked", function()
+		local dose = MetricUnit.new(2, "joule") / MetricUnit.kilograms(1)
+		expect(dose:GetKind()).toBe("absorbedDose")
+		expect(format(dose)).toBe("2 Gy")
+		expect(format(dose:As("sievert"))).toBe("2 Sv")
+		expect(MetricUnit.new(5, "becquerel"):In("hertz")).toBe(5)
+		expect(format(MetricUnit.new(3, "millisievert"))).toBe("3 mGy")
+	end)
+end)

package/src/Shared/MetricUnit.Spring.spec.lua

@@ -0,0 +1,94 @@
+--!strict
+--[[
+	@class MetricUnit.Spring.spec.lua
+]]
+
+local require = require(script.Parent.loader).load(script)
+
+local Jest = require("Jest")
+local LinearValue = require("LinearValue")
+local MetricUnit = require("MetricUnit")
+local Spring = require("Spring")
+
+local describe = Jest.Globals.describe
+local expect = Jest.Globals.expect
+local it = Jest.Globals.it
+
+local function manualClock(): (() -> number, (number) -> ())
+	local now = 0
+	return function()
+		return now
+	end, function(seconds: number)
+		now += seconds
+	end
+end
+
+describe("MetricUnit in a Spring", function()
+	it("animates a length to its target", function()
+		local clock, advance = manualClock()
+		local spring = Spring.new(MetricUnit.meters(0), clock)
+		spring.Speed = 20
+		spring.Target = MetricUnit.meters(10)
+
+		advance(0.05)
+		local midway = (spring.Position :: any):In("meter")
+		expect(midway > 0 and midway < 10).toBe(true)
+		-- Spring's clock is a plain number, so its velocity is in the position's units per second
+		expect((spring.Velocity :: any):GetKind()).toBe("length")
+
+		advance(10)
+		expect((spring.Position :: any):In("meter")).toBeCloseTo(10, 6)
+		expect((spring.Velocity :: any):In("meter")).toBeCloseTo(0, 6)
+	end)
+
+	it("starts from a spring made with no initial value", function()
+		local clock, advance = manualClock()
+		local spring = Spring.new(nil :: any, clock)
+		spring.Target = MetricUnit.new(5, "volt")
+		advance(30)
+		expect((spring.Position :: any):In("volt")).toBeCloseTo(5, 6)
+	end)
+
+	it("takes an impulse in the position's units, and refuses one of another dimension", function()
+		local clock, advance = manualClock()
+		local spring = Spring.new(MetricUnit.meters(0), clock)
+		spring:Impulse(MetricUnit.meters(4))
+		advance(0.01)
+		expect((spring.Position :: any):In("meter") > 0).toBe(true)
+		expect(function()
+			spring:Impulse(MetricUnit.new(4, "meterPerSecond") :: any)
+		end).toThrow()
+	end)
+
+	it("skips time and snaps to a target without animating", function()
+		local clock = manualClock()
+		local spring = Spring.new(MetricUnit.celsius(0) - MetricUnit.celsius(0), clock)
+		spring:SetTarget(MetricUnit.difference(20, "celsius"), true)
+		expect((spring.Position :: any):In("kelvin")).toBe(20)
+		spring.Target = MetricUnit.difference(0, "celsius")
+		spring:TimeSkip(60)
+		expect((spring.Position :: any):In("kelvin")).toBeCloseTo(0, 6)
+	end)
+
+	it("springs an absolute value through its offset from a reference", function()
+		expect(function()
+			Spring.new(MetricUnit.celsius(20))
+		end).toThrow("cannot multiply an absolute temperature")
+
+		local clock, advance = manualClock()
+		local reference = MetricUnit.celsius(0)
+		local spring = Spring.new(MetricUnit.celsius(15) - reference, clock)
+		spring.Target = MetricUnit.celsius(25) - reference
+		advance(60)
+		expect((reference + spring.Position :: any):In("celsius")).toBeCloseTo(25, 6)
+	end)
+end)
+
+describe("MetricUnit and LinearValue", function()
+	it("passes through LinearValue untouched, since it is linear already", function()
+		local value = MetricUnit.meters(3)
+		expect(LinearValue.isLinear(value)).toBe(false)
+		expect(LinearValue.toLinearIfNeeded(value)).toBe(value)
+		expect(LinearValue.fromLinearIfNeeded(value)).toBe(value)
+	end)
+end)