@quenty/metricutils 2.4.3 → 2.5.0

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

@@ -0,0 +1,212 @@
+--!strict
+--[[
+	@class MetricUnit.Temperature.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 YEAR = MetricUnit.years(1):InSeconds()
+
+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
+
+describe("MetricUnit absolute temperatures", function()
+	it("reads each scale back from its own zero", function()
+		expect(MetricUnit.celsius(5):In("celsius")).toBeCloseTo(5, 9)
+		expect(MetricUnit.celsius(5):In("kelvin")).toBeCloseTo(278.15, 9)
+		expect(MetricUnit.kelvin(0):In("celsius")).toBeCloseTo(-273.15, 9)
+		expect(MetricUnit.fahrenheit(212):In("celsius")).toBeCloseTo(100, 9)
+		expect(MetricUnit.celsius(-40):In("fahrenheit")).toBeCloseTo(-40, 9)
+		expect(MetricUnit.fahrenheit(32):In("fahrenheit")).toBeCloseTo(32, 9)
+		expect(MetricUnit.isKind(MetricUnit.kelvin(300), "temperature")).toBe(true)
+		expect((MetricUnit.celsius(5)):IsAbsolute()).toBe(true)
+	end)
+
+	it("subtracts two absolutes to a difference", function()
+		local difference = MetricUnit.celsius(5) - MetricUnit.celsius(2)
+		expect(MetricUnit.isKind(difference, "temperatureDifference")).toBe(true)
+		expect((difference):IsAbsolute()).toBe(false)
+		expect(difference:In("kelvin")).toBeCloseTo(3, 9)
+		expect(difference:In("celsius")).toBeCloseTo(3, 9)
+		expect(difference:In("fahrenheit")).toBeCloseTo(5.4, 9)
+	end)
+
+	it("adds a difference to an absolute, on either side, to an absolute", function()
+		local swing = MetricUnit.difference(12, "celsius")
+		expect((MetricUnit.celsius(15) + swing):In("celsius")).toBeCloseTo(27, 9)
+		expect((swing + MetricUnit.celsius(15)):In("celsius")).toBeCloseTo(27, 9)
+		expect((MetricUnit.celsius(15) - swing):In("celsius")).toBeCloseTo(3, 9)
+		expect(MetricUnit.isKind(MetricUnit.celsius(15) - swing, "temperature")).toBe(true)
+		expect((MetricUnit.celsius(15) + 0):In("celsius")).toBeCloseTo(15, 9)
+	end)
+
+	it("errors adding two absolutes", function()
+		expect(function()
+			local _ = MetricUnit.celsius(5) + MetricUnit.celsius(2)
+		end).toThrow(
+			"cannot add two absolute temperatures; subtract them for a difference, or add a difference to one"
+		)
+	end)
+
+	it("errors subtracting an absolute from a difference", function()
+		expect(function()
+			local _ = MetricUnit.difference(5, "celsius") - MetricUnit.celsius(2)
+		end).toThrow("cannot subtract an absolute temperature from a temperature difference")
+		expect(function()
+			local _ = 0 - MetricUnit.celsius(2)
+		end).toThrow("cannot subtract an absolute temperature from a temperature difference")
+	end)
+
+	it("errors scaling, negating or taking powers of an absolute, kelvin included", function()
+		expect(function()
+			local _ = MetricUnit.celsius(5) * 2
+		end).toThrow("cannot multiply an absolute temperature")
+		expect(function()
+			local _ = 2 * MetricUnit.kelvin(300)
+		end).toThrow("cannot multiply an absolute temperature")
+		expect(function()
+			local _ = MetricUnit.kelvin(300) / MetricUnit.seconds(1)
+		end).toThrow("cannot divide an absolute temperature")
+		expect(function()
+			local _ = -MetricUnit.celsius(5)
+		end).toThrow("cannot negate an absolute temperature")
+		expect(function()
+			MetricUnit.abs(MetricUnit.celsius(5))
+		end).toThrow("cannot take the size of an absolute temperature")
+		expect(function()
+			MetricUnit.pow(MetricUnit.celsius(5), 2)
+		end).toThrow("cannot exponentiate an absolute temperature")
+	end)
+
+	it("errors reading an absolute with In or a non-temperature reader", function()
+		expect(function()
+			MetricUnit.celsius(5):In(MetricUnit.difference(1, "kelvin"))
+		end).toThrow("cannot take the ratio of an absolute temperature")
+		expect(function()
+			MetricUnit.celsius(5):In("day")
+		end).toThrow('In("day") reads time, not absolute temperature')
+		expect(function()
+			MetricUnit.kilometers(5):In("celsius")
+		end).toThrow('In("celsius") reads temperature, not length')
+	end)
+end)
+
+describe("MetricUnit temperature differences", function()
+	it("makes differences on each scale", function()
+		expect(MetricUnit.difference(3, "kelvin"):In("kelvin")).toBe(3)
+		expect(MetricUnit.difference(3, "celsius"):In("kelvin")).toBe(3)
+		expect(MetricUnit.difference(9, "fahrenheit"):In("celsius")).toBeCloseTo(5, 9)
+		expect(MetricUnit.isKind(MetricUnit.difference(1, "celsius"), "temperatureDifference")).toBe(true)
+		expect(MetricUnit.isKind(MetricUnit.difference(1, "celsius"), "temperature")).toBe(false)
+	end)
+
+	it("scales, negates and divides freely", function()
+		local swing = MetricUnit.difference(12, "celsius")
+		expect((swing * 0.5):In("celsius")).toBeCloseTo(6, 9)
+		expect((-swing):In("celsius")).toBeCloseTo(-12, 9)
+		expect((swing / MetricUnit.years(1)):In(MetricUnit.difference(1, "kelvin") / MetricUnit.days(1))).toBeCloseTo(
+			12 * DAY / YEAR,
+			12
+		)
+	end)
+end)
+
+describe("MetricUnit temperature comparisons", function()
+	it("compares two absolutes or two differences", function()
+		expect(MetricUnit.celsius(5) < MetricUnit.celsius(6)).toBe(true)
+		expect(MetricUnit.celsius(5) == MetricUnit.kelvin(278.15)).toBe(true)
+		expect(MetricUnit.fuzzyEq(MetricUnit.fahrenheit(32), MetricUnit.celsius(0))).toBe(true)
+		expect(MetricUnit.difference(1, "celsius") <= MetricUnit.difference(2, "fahrenheit")).toBe(true)
+		expect(MetricUnit.max(MetricUnit.celsius(5), MetricUnit.celsius(9)):In("celsius")).toBeCloseTo(9, 9)
+		expect(MetricUnit.isKind(MetricUnit.max(MetricUnit.celsius(5), MetricUnit.celsius(9)), "temperature")).toBe(
+			true
+		)
+	end)
+
+	it("errors comparing an absolute with a difference", function()
+		expect(function()
+			local _ = MetricUnit.celsius(5) < MetricUnit.difference(6, "celsius")
+		end).toThrow("cannot compare an absolute temperature and a temperature difference")
+		expect(function()
+			local _ = MetricUnit.celsius(5) == MetricUnit.difference(5, "kelvin")
+		end).toThrow("cannot compare an absolute temperature and a temperature difference")
+		expect(function()
+			MetricUnit.max(MetricUnit.celsius(5), 0)
+		end).toThrow("cannot compare absolute temperature and the plain number 0")
+	end)
+end)
+
+describe("MetricUnit temperature boundaries and data", function()
+	it("expects an absolute temperature or a difference by name", function()
+		expect(MetricUnit.expect(MetricUnit.celsius(5), "temperature", "air")).toBeCloseTo(278.15, 9)
+		expect(MetricUnit.expect(MetricUnit.difference(12, "celsius"), "temperatureDifference", "swing")).toBe(12)
+		expect(MetricUnit.expect(0, "temperatureDifference", "swing")).toBe(0)
+		expect(function()
+			MetricUnit.expect(MetricUnit.difference(12, "celsius"), "temperature", "air")
+		end).toThrow("MetricUnit.expect: air expects absolute temperature, got temperature difference")
+		expect(function()
+			MetricUnit.expect(MetricUnit.celsius(12), "temperatureDifference", "swing")
+		end).toThrow("MetricUnit.expect: swing expects temperature difference, got absolute temperature")
+		expect(function()
+			MetricUnit.expect(0, "temperature", "air")
+		end).toThrow("MetricUnit.expect: air expects absolute temperature, got the plain number 0")
+	end)
+
+	it("round trips an absolute through plain data", function()
+		local data = MetricUnit.toData(MetricUnit.kelvin(300))
+		expect(data).toEqual({ amount = 300, dimensions = { temperature = 1 }, absolute = true })
+		local back = MetricUnit.fromData(data)
+		expect(MetricUnit.isKind(back, "temperature")).toBe(true)
+		expect(back:In("kelvin")).toBe(300)
+		expect(MetricUnit.toData(MetricUnit.difference(3, "kelvin"))).toEqual({
+			amount = 3,
+			dimensions = { temperature = 1 },
+		})
+	end)
+end)
+
+describe("MetricUnit.point and MetricUnit.difference", function()
+	it("makes a point from a unit's zero, in any unit", function()
+		expect(MetricUnit.point(20, "celsius") == MetricUnit.celsius(20)).toBe(true)
+		expect(MetricUnit.point(90, "second") == MetricUnit.instant(90)).toBe(true)
+		expect(MetricUnit.point(1.5, "minute"):In("second")).toBe(90)
+		expect(MetricUnit.point(5, "meter"):IsAbsolute()).toBe(true)
+	end)
+
+	it("makes a difference, in any unit", function()
+		expect(MetricUnit.difference(9, "fahrenheit"):In("kelvin")).toBeCloseTo(5, 9)
+		expect(MetricUnit.difference(12, "celsius"):IsAbsolute()).toBe(false)
+		expect(MetricUnit.difference(5, "meter") == MetricUnit.meters(5)).toBe(true)
+	end)
+
+	it("follows the point rules for every dimension", function()
+		local gap = MetricUnit.point(7, "meter") - MetricUnit.point(2, "meter")
+		expect(gap == MetricUnit.meters(5)).toBe(true)
+		expect(function()
+			local _ = MetricUnit.point(7, "meter") + MetricUnit.point(2, "meter")
+		end).toThrow()
+	end)
+
+	it("formats a point on the scale people read and a difference in kelvin", function()
+		expect(format(MetricUnit.point(20, "celsius"))).toBe("20 °C")
+		expect(format(MetricUnit.difference(20, "celsius"))).toBe("20 K")
+	end)
+
+	it("errors on an unknown unit or a non-number", function()
+		expect(function()
+			MetricUnit.point(1, "klicks" :: any)
+		end).toThrow('MetricUnit.point knows no unit "klicks"')
+		expect(function()
+			MetricUnit.difference("1" :: any, "meter")
+		end).toThrow("MetricUnit.difference takes a number")
+	end)
+end)

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

@@ -0,0 +1,202 @@
+--!strict
+--[[
+	@class MetricUnit.Time.spec.lua
+]]
+
+local require = require(script.Parent.loader).load(script)
+
+local Jest = require("Jest")
+local MetricUnit = require("MetricUnit")
+local TimeDurationUtils = require("TimeDurationUtils")
+local TimeLocalizationUtils = require("TimeLocalizationUtils")
+
+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
+
+-- 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
+
+describe("MetricUnit.format durations", function()
+	it("writes averaged years and months whole", function()
+		expect(format(MetricUnit.years(1))).toBe("1 year")
+		expect(format(MetricUnit.months(1))).toBe("1 month")
+		expect(format(MetricUnit.years(1) / 12)).toBe("1 month")
+		expect(format(MetricUnit.months(12))).toBe("1 year")
+		expect(format(MetricUnit.years(100))).toBe("100 years")
+		expect(format(MetricUnit.years(1) + MetricUnit.days(1))).toBe("1 year, 1 day")
+	end)
+
+	it("breaks a duration into its two largest units", function()
+		expect(format(MetricUnit.minutes(90))).toBe("1 hour, 30 minutes")
+		expect(format(MetricUnit.days(1.5))).toBe("1 day, 12 hours")
+		expect(format(MetricUnit.hours(36.6))).toBe("1 day, 13 hours")
+		expect(format(MetricUnit.seconds(45))).toBe("45 seconds")
+		expect(format(MetricUnit.years(1234))).toBe("1,234 years")
+	end)
+
+	it("carries a rounded unit into the next larger one", function()
+		expect(format(MetricUnit.days(1) + MetricUnit.hours(23) + MetricUnit.minutes(59.7))).toBe("2 days")
+		expect(format(MetricUnit.minutes(59.9), { maxParts = 1 })).toBe("1 hour")
+	end)
+
+	it("takes how many units to show and the separator", function()
+		expect(format(MetricUnit.minutes(90), { maxParts = 1 })).toBe("2 hours")
+		expect(format(MetricUnit.days(1) + MetricUnit.hours(2) + MetricUnit.minutes(3), { maxParts = 3 })).toBe(
+			"1 day, 2 hours, 3 minutes"
+		)
+		expect(format(MetricUnit.minutes(90), { separator = " " })).toBe("1 hour 30 minutes")
+	end)
+
+	it("writes zero, milliseconds and less than a millisecond", function()
+		expect(format(MetricUnit.seconds(0))).toBe("0 seconds")
+		expect(format(MetricUnit.milliseconds(250))).toBe("250 milliseconds")
+		expect(format(MetricUnit.new(40, "microsecond"))).toBe("40 microseconds")
+	end)
+
+	it("signs a negative duration once", function()
+		expect(format(-MetricUnit.minutes(90))).toBe("-1 hour, 30 minutes")
+	end)
+
+	it("writes one fixed time unit with a fractional amount", function()
+		expect(format(MetricUnit.minutes(90), { unit = "hour" })).toBe("1.5 hours")
+		expect(format(MetricUnit.hours(1), { unit = "hour" })).toBe("1 hour")
+		expect(format(MetricUnit.hours(36), { unit = "day", locale = "es-es" })).toBe("1,5 días")
+	end)
+
+	it("uses @quenty/time's localized duration words", function()
+		expect(format(MetricUnit.minutes(90), { locale = "es-es" })).toBe("1 hora, 30 minutos")
+		expect(format(MetricUnit.days(2), { locale = "fr-fr" })).toBe("2 jours")
+		expect(format(MetricUnit.hours(2), { locale = "ru-ru" })).toBe("2 часа")
+		local hours: TimeLocalizationUtils.DurationPhrase = { one = "%d hr", other = "%d hrs" }
+		expect(format(MetricUnit.minutes(90), { durationStrings = { hours = hours } })).toBe("1 hr, 30 minutes")
+	end)
+end)
+
+describe("MetricUnit.format clock durations", function()
+	it("writes a clock, minutes and seconds under an hour", function()
+		expect(format(MetricUnit.minutes(90), { durationStyle = "clock" })).toBe("1:30:00")
+		expect(format(MetricUnit.seconds(45), { durationStyle = "clock" })).toBe("0:45")
+		expect(format(MetricUnit.seconds(3725), { durationStyle = "clock" })).toBe("1:02:05")
+		expect(format(MetricUnit.hours(30), { durationStyle = "clock" })).toBe("30:00:00")
+	end)
+
+	it("passes a template to TimeDurationUtils, refusing years and months", function()
+		expect(format(MetricUnit.seconds(90), { durationTemplate = "mm:ss" })).toBe("01:30")
+		expect(format(MetricUnit.days(2), { durationTemplate = "d __" })).toBe("2 days")
+		expect(format(MetricUnit.seconds(90), { durationTemplate = "[at] m:ss" })).toBe("at 1:30")
+		expect(function()
+			format(MetricUnit.years(1), { durationTemplate = "y __" })
+		end).toThrow("counts years or months")
+	end)
+end)
+
+describe("MetricUnit and @quenty/time", function()
+	it("hands exact seconds to TimeDurationUtils", function()
+		expect(MetricUnit.minutes(2):InSeconds()).toBe(120)
+		expect(TimeDurationUtils.format(MetricUnit.hours(36):InSeconds(), "h:mm")).toBe("36:00")
+		expect(MetricUnit.years(1):InSeconds()).toBe(YEAR)
+	end)
+
+	it("measures the exact time between two DateTimes", function()
+		local start = MetricUnit.fromDateTime(DateTime.fromUnixTimestamp(0))
+		local later = MetricUnit.fromDateTime(DateTime.fromUnixTimestamp(90))
+		expect((later - start):InSeconds()).toBe(90)
+		expect((start - later):InSeconds()).toBe(-90)
+		expect(MetricUnit.isKind(later - start, "time")).toBe(true)
+
+		-- A calendar year with a leap day is 366 days, longer than the averaged year
+		local leapYear = MetricUnit.fromDateTime(DateTime.fromUniversalTime(2025, 1, 1))
+			- MetricUnit.fromDateTime(DateTime.fromUniversalTime(2024, 1, 1))
+		expect(leapYear:In("day")).toBe(366)
+		expect(leapYear > MetricUnit.years(1)).toBe(true)
+	end)
+
+	it("moves a DateTime by an exact span", function()
+		local start = MetricUnit.fromDateTime(DateTime.fromUnixTimestamp(0))
+		expect((start + MetricUnit.hours(1)):ToDateTime().UnixTimestamp).toBe(3600)
+		expect((start + MetricUnit.months(1)):ToDateTime().UnixTimestampMillis).toBe(MONTH * 1000)
+	end)
+end)
+
+describe("MetricUnit instants", function()
+	it("subtracts two instants to a span, and adds a span to an instant", function()
+		local worldStart = MetricUnit.instant(0)
+		local now = worldStart + MetricUnit.years(250)
+		expect(MetricUnit.isKind(now, "instant")).toBe(true)
+		expect(now:IsAbsolute()).toBe(true)
+		expect(now:GetKind()).toBe("instant")
+		expect((now - worldStart):GetKind()).toBe("time")
+		expect((now - worldStart):In("year")).toBeCloseTo(250, 9)
+		expect((MetricUnit.years(1) + now - now):In("year")).toBeCloseTo(1, 9)
+		expect(MetricUnit.isKind(now - MetricUnit.days(1), "instant")).toBe(true)
+		expect(MetricUnit.isKind(now, "time")).toBe(false)
+	end)
+
+	it("reads an instant as the time since its epoch", function()
+		local instant = MetricUnit.instant(5400)
+		expect(instant:InSeconds()).toBe(5400)
+		expect(instant:In("hour")).toBe(1.5)
+		expect(function()
+			instant:In("meter")
+		end).toThrow('In("meter") reads length, not instant')
+	end)
+
+	it("rejects adding, scaling and negating instants", function()
+		local instant = MetricUnit.instant(10)
+		expect(function()
+			local _ = instant + instant
+		end).toThrow("cannot add two instants; subtract them for a difference, or add a difference to one")
+		expect(function()
+			local _ = MetricUnit.seconds(1) - instant
+		end).toThrow("cannot subtract an instant from a time")
+		expect(function()
+			local _ = instant * 2
+		end).toThrow("cannot multiply an instant")
+		expect(function()
+			local _ = -instant
+		end).toThrow("cannot negate an instant")
+		expect(function()
+			MetricUnit.abs(instant)
+		end).toThrow("cannot take the size of an instant")
+		expect(function()
+			local _ = instant < MetricUnit.seconds(20)
+		end).toThrow("cannot compare an instant and a time")
+	end)
+
+	it("expects instants and spans apart", function()
+		expect(MetricUnit.expect(MetricUnit.instant(7), "instant", "at")).toBe(7)
+		expect(function()
+			MetricUnit.expect(MetricUnit.seconds(7), "instant", "at")
+		end).toThrow("MetricUnit.expect: at expects instant, got time")
+		expect(function()
+			MetricUnit.expect(MetricUnit.instant(7), "time", "every")
+		end).toThrow("MetricUnit.expect: every expects time, got instant")
+	end)
+
+	it("round trips through DateTime and plain data", function()
+		local dateTime = DateTime.fromUnixTimestampMillis(1_700_000_000_123)
+		expect(MetricUnit.fromDateTime(dateTime):ToDateTime().UnixTimestampMillis).toBe(1_700_000_000_123)
+		expect(function()
+			MetricUnit.seconds(5):ToDateTime()
+		end).toThrow("ToDateTime takes an instant, not time")
+
+		local data = MetricUnit.toData(MetricUnit.instant(42))
+		expect(data).toEqual({ amount = 42, dimensions = { time = 1 }, absolute = true })
+		expect(MetricUnit.isKind(MetricUnit.fromData(data), "instant")).toBe(true)
+	end)
+
+	it("writes an instant apart from a span", function()
+		expect(tostring(MetricUnit.instant(90))).toBe("epoch + " .. tostring(MetricUnit.seconds(90)))
+		expect(format(MetricUnit.instant(5400))).toBe("1 hour, 30 minutes")
+	end)
+end)

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

@@ -0,0 +1,210 @@
+--!strict
+--[[
+	@class MetricUnit.Units.spec.lua
+]]
+
+local require = require(script.Parent.loader).load(script)
+
+local Jest = require("Jest")
+local MetricUnit = require("MetricUnit")
+local MetricUnitDefinitions = require("MetricUnitDefinitions")
+local MetricUtils = require("MetricUtils")
+
+local describe = Jest.Globals.describe
+local expect = Jest.Globals.expect
+local it = Jest.Globals.it
+
+-- 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
+
+describe("MetricUnit:In", function()
+	it("reads by unit id, by @quenty/time's names for time, and by unit value", function()
+		expect(MetricUnit.kilometers(2):In("meter")).toBe(2000)
+		expect(MetricUnit.minutes(90):In("hour")).toBe(1.5)
+		expect(MetricUnit.minutes(90):In("hours")).toBe(1.5)
+		expect(MetricUnit.minutes(90):In("h")).toBe(1.5)
+		expect(MetricUnit.minutes(90):In(MetricUnit.hours(1))).toBe(1.5)
+		expect(MetricUnit.perDay(48):In("perHour")).toBeCloseTo(2, 9)
+		expect(MetricUnit.years(1):In("quarter")).toBeCloseTo(4, 9)
+	end)
+
+	it("reads a temperature scale from its zero when absolute", function()
+		expect(MetricUnit.celsius(100):In("fahrenheit")).toBeCloseTo(212, 9)
+		expect(MetricUnit.difference(5, "celsius"):In("fahrenheit")).toBeCloseTo(9, 9)
+	end)
+
+	it("errors on an unknown id, and on another dimension naming both", function()
+		expect(function()
+			MetricUnit.meters(1):In("klicks" :: any)
+		end).toThrow('MetricUnit:In knows no unit "klicks"')
+		expect(function()
+			MetricUnit.meters(1):In("second")
+		end).toThrow('In("second") reads time, not length')
+		expect(function()
+			MetricUnit.seconds(1):InSeconds()
+		end).never.toThrow()
+	end)
+end)
+
+describe("MetricUnit.new", function()
+	it("makes a value from an amount and a unit id", function()
+		expect(MetricUnit.new(5, "kilometer") == MetricUnit.kilometers(5)).toBe(true)
+		expect(MetricUnit.new(90, "minutes") == MetricUnit.hours(1.5)).toBe(true)
+		expect(MetricUnit.new(20, "celsius"):IsAbsolute()).toBe(true)
+		expect(function()
+			MetricUnit.new(1, "klicks" :: any)
+		end).toThrow('MetricUnit.new knows no unit "klicks"')
+	end)
+end)
+
+describe("MetricUnit dimension queries", function()
+	it("names what a value measures", function()
+		expect(MetricUnit.kilometers(1):GetKind()).toBe("length")
+		expect((MetricUnit.kilometers(1) / MetricUnit.hours(1)):GetKind()).toBe("speed")
+		expect(MetricUnit.celsius(5):GetKind()).toBe("temperature")
+		expect(MetricUnit.difference(5, "celsius"):GetKind()).toBe("temperatureDifference")
+		expect(MetricUnit.none(1):GetKind()).toBe("none")
+		expect(MetricUnit.pow(MetricUnit.meters(1), 4):GetKind()).toBeNil()
+	end)
+
+	it("checks kinds by name or exponents, and errors on an unknown name", function()
+		local speed = MetricUnit.meters(1) / MetricUnit.seconds(1)
+		expect(speed:IsKind("speed")).toBe(true)
+		expect(speed:IsKind({ length = 1, time = -1 })).toBe(true)
+		expect(MetricUnit.isKind(speed, "length")).toBe(false)
+		expect(MetricUnit.isKind(5, "length")).toBe(false)
+		expect(function()
+			MetricUnit.isKind(speed, "velocity" :: any)
+		end).toThrow('no kind named "velocity"')
+	end)
+
+	it("gives the base amount, frozen dimensions and absoluteness", function()
+		local length = MetricUnit.kilometers(2)
+		expect(length:GetBaseAmount()).toBe(2000)
+		expect(length:GetDimensions()).toEqual({ length = 1 })
+		expect(table.isfrozen(length:GetDimensions())).toBe(true)
+		expect(length:IsAbsolute()).toBe(false)
+	end)
+
+	it("lists the unit ids a value can be read in, metric first", function()
+		local ids = MetricUnit.meters(1):GetUnitIds()
+		expect(ids[1]).toBe("meter")
+		expect(table.find(ids, "nanometer")).never.toBeNil()
+		expect(table.find(ids, "mile")).never.toBeNil()
+		expect(table.find(ids, "stud")).never.toBeNil()
+		expect(table.find(ids, "kilogram")).toBeNil()
+		expect(table.find(MetricUnit.celsius(5):GetUnitIds(), "fahrenheit")).never.toBeNil()
+	end)
+end)
+
+describe("MetricUnit studs", function()
+	it("counts a stud as 28 cm, as Roblox documents it", function()
+		expect(MetricUnitDefinitions.ROBLOX_METERS_PER_STUD).toBe(0.28)
+		expect(MetricUnit.studs(100):In("meter")).toBeCloseTo(28, 9)
+		expect(MetricUnit.meters(1):In("stud")).toBeCloseTo(1 / 0.28, 9)
+		expect(MetricUnit.new(100, "studPerSecond"):In("meterPerSecond")).toBeCloseTo(28, 9)
+	end)
+
+	it("keeps MetricUtils at the 3.57 studs to the metre it has always used", function()
+		expect(MetricUtils.studsToMeters(357)).toBeCloseTo(100, 9)
+		expect(MetricUtils.studsPerSecondToMetersPerSecond(35.7)).toBeCloseTo(10, 9)
+	end)
+
+	it("shows studs as studs, until converted", function()
+		expect(format(MetricUnit.studs(250))).toBe("250 studs")
+		expect(format(MetricUnit.studs(250):ToMetric())).toBe("70 m")
+		expect(format(MetricUnit.studs(250), { unit = "stud" })).toBe("250 studs")
+		expect(format(MetricUnit.studs(1), { unit = "stud" })).toBe("1 stud")
+		expect(format(MetricUnit.new(16, "studPerSecond"), { unit = "studPerSecond" })).toBe("16 studs/s")
+		expect(format(MetricUnit.studs(250):ToUSCustomary())).toBe("229.659 ft")
+	end)
+end)
+
+describe("MetricUnit US customary units", function()
+	it("converts with exact definitions", function()
+		expect(MetricUnit.new(1, "inch"):In("millimeter")).toBeCloseTo(25.4, 9)
+		expect(MetricUnit.fuzzyEq(MetricUnit.new(3, "foot"), MetricUnit.new(1, "yard"))).toBe(true)
+		expect(MetricUnit.new(1, "mile"):In("foot")).toBeCloseTo(5280, 9)
+		expect(MetricUnit.new(1, "pound"):In("kilogram")).toBe(0.45359237)
+		expect(MetricUnit.new(1, "pound"):In("ounce")).toBeCloseTo(16, 9)
+		expect(MetricUnit.new(1, "stone"):In("pound")).toBeCloseTo(14, 9)
+		expect(MetricUnit.new(1, "acre"):In("squareFoot")).toBeCloseTo(43560, 6)
+		expect(MetricUnit.new(1, "usGallon"):In("usFluidOunce")).toBeCloseTo(128, 9)
+		expect(MetricUnit.new(1, "imperialGallon"):In("liter")).toBeCloseTo(4.54609, 9)
+		expect(MetricUnit.new(60, "milePerHour"):In("kilometerPerHour")).toBeCloseTo(96.56064, 9)
+		expect(MetricUnit.new(1, "knot"):In("kilometerPerHour")).toBeCloseTo(1.852, 9)
+		expect(MetricUnit.new(1, "poundForce"):In("newton")).toBeCloseTo(4.4482216152605, 12)
+		expect(MetricUnit.new(1, "poundForcePerSquareInch"):In("pascal")).toBeCloseTo(6894.757293168, 6)
+		expect(
+			(MetricUnit.new(1, "poundForce") / MetricUnit.pow(MetricUnit.new(1, "inch"), 2)):In(
+				"poundForcePerSquareInch"
+			)
+		).toBeCloseTo(1, 12)
+	end)
+
+	it("shows a value made in a customary unit in customary units, until converted", function()
+		expect(format(MetricUnit.new(1, "mile"))).toBe("1 mi")
+		expect(format(MetricUnit.new(1, "mile"):ToMetric())).toBe("1.609 km")
+		expect(format(MetricUnit.kilometers(1.609))).toBe("1.609 km")
+		expect(format(MetricUnit.new(1, "mile"), { unit = "mile" })).toBe("1 mi")
+		expect(format(MetricUnit.new(2, "foot"), { unit = "foot", unitDisplay = "long" })).toBe("2 feet")
+		expect(format(MetricUnit.new(1, "foot"), { unit = "foot", unitDisplay = "long" })).toBe("1 foot")
+	end)
+
+	it("picks customary units for a value that prefers them", function()
+		local function usCustomary(value: MetricUnit.MetricUnit): string
+			return format(value:ToUSCustomary())
+		end
+		expect(usCustomary(MetricUnit.kilometers(5))).toBe("3.107 mi")
+		expect(usCustomary(MetricUnit.meters(1))).toBe("3.281 ft")
+		expect(usCustomary(MetricUnit.new(10, "centimeter"))).toBe("3.937 in")
+		expect(usCustomary(MetricUnit.kilograms(1))).toBe("2.205 lb")
+		expect(usCustomary(MetricUnit.new(100, "kilometerPerHour"))).toBe("62.137 mph")
+		expect(usCustomary(MetricUnit.celsius(100))).toBe("212 °F")
+		expect(usCustomary(MetricUnit.difference(5, "celsius"))).toBe("9 °F")
+		expect(usCustomary(MetricUnit.new(1, "bar"))).toBe("14.504 psi")
+		expect(usCustomary(MetricUnit.new(1500, "joule"))).toBe("1.422 Btu")
+		-- Dimensions without US customary display units stay metric
+		expect(usCustomary(MetricUnit.new(5, "volt"))).toBe("5 V")
+		expect(format(MetricUnit.kilometers(5):ToUSCustomary(), { autoUnit = false })).toBe("5,000 m")
+	end)
+end)
+
+describe("MetricUnit bits", function()
+	it("shares the memory dimension with bytes, eight to a byte", function()
+		expect(MetricUnit.new(8, "bit") == MetricUnit.bytes(1)).toBe(true)
+		expect(MetricUnit.new(8, "megabit"):In("kilobyte")).toBeCloseTo(1000, 9)
+		expect(MetricUnit.new(8, "megabitPerSecond"):In("kilobytePerSecond")).toBeCloseTo(1000, 9)
+		expect(MetricUnit.new(1, "gigabitPerSecond"):GetKind()).toBe("dataRate")
+	end)
+
+	it("never switches between bits and bytes on its own", function()
+		expect(format(MetricUnit.new(8, "bit"))).toBe("1 B")
+		expect(format(MetricUnit.new(8, "kilobit"), { unit = "kilobit" })).toBe("8 kbit")
+		expect(format(MetricUnit.new(100, "megabitPerSecond"), { unit = "megabitPerSecond" })).toBe("100 Mbit/s")
+	end)
+end)
+
+describe("MetricUnit percentages", function()
+	it("reads and makes dimensionless proportions", function()
+		expect(MetricUnit.percent(45):In("percent")).toBeCloseTo(45, 9)
+		expect(MetricUnit.percent(45):GetBaseAmount()).toBeCloseTo(0.45, 12)
+		expect(MetricUnit.new(5, "permille"):In("percent")).toBeCloseTo(0.5, 12)
+		expect((MetricUnit.percent(45) * MetricUnit.meters(10)):In("meter")).toBeCloseTo(4.5, 9)
+	end)
+
+	it("formats a proportion as a percent only on request", function()
+		local used = MetricUnit.kilobytes(450) / MetricUnit.megabytes(1)
+		expect(format(used)).toBe("0.45")
+		expect(format(used, { unit = "percent" })).toBe("45%")
+		expect(format(used, { unit = "percent", unitDisplay = "long" })).toBe("45 percent")
+		expect(format(MetricUnit.new(5, "permille"), { unit = "permille" })).toBe("5‰")
+		expect(format(MetricUnit.percent(45):As("percent"))).toBe("45%")
+	end)
+end)