@quenty/metricutils 2.4.3 → 2.5.0

package/src/Shared/Definitions/MetricUnitDefinitions.spec.lua

@@ -0,0 +1,55 @@
+--!strict
+--[[
+	@class MetricUnitDefinitions.spec.lua
+]]
+
+local require = require(script.Parent.loader).load(script)
+
+local Jest = require("Jest")
+local MetricUnit = require("MetricUnit")
+local MetricUnitDefinitions = require("MetricUnitDefinitions")
+local MetricUnitDimensionUtils = require("MetricUnitDimensionUtils")
+
+local describe = Jest.Globals.describe
+local expect = Jest.Globals.expect
+local it = Jest.Globals.it
+
+-- A unit is written by name unless @quenty/time's duration words or a per phrase write it
+local function isWrittenByName(unit: MetricUnitDefinitions.UnitDefinition): boolean
+	return unit.per == nil and (not unit.duration or unit.id == "microsecond")
+end
+
+describe("MetricUnitDefinitions", function()
+	it("declares each unit once, and every unit makes and reads back through MetricUnit.new", function()
+		local seen: { [string]: boolean } = {}
+		for _, unit in MetricUnitDefinitions.getUnits() do
+			expect(seen[unit.id]).toBeNil()
+			seen[unit.id] = true
+			expect(MetricUnitDefinitions.getUnit(unit.id)).toBe(unit)
+			expect(MetricUnit.new(1, unit.id):In(unit.id)).toBeCloseTo(1, 9)
+			expect(MetricUnitDimensionUtils.isDimensions(unit.dimensions)).toBe(true)
+			expect(unit.factor > 0).toBe(true)
+		end
+	end)
+
+	it("gives English names to every unit written by name, and to no other", function()
+		for _, unit in MetricUnitDefinitions.getUnits() do
+			if isWrittenByName(unit) then
+				local names = unit.names
+				assert(names, string.format("%s has no English names", unit.id))
+				expect(#names.one > 0 and #names.other > 0).toBe(true)
+			else
+				expect(unit.names).toBeNil()
+			end
+		end
+	end)
+
+	it("resolves @quenty/time's names to time units", function()
+		for alias, id in MetricUnitDefinitions.getTimeAliases() do
+			local unit = MetricUnitDefinitions.getUnit(alias)
+			assert(unit, alias)
+			expect(unit.id).toBe(id)
+			expect(unit.duration).toBe(true)
+		end
+	end)
+end)

package/src/Shared/Definitions/MetricUnitDimensionUtils.lua

@@ -0,0 +1,164 @@
+--!strict
+--[=[
+	Functions over dimensions: frozen tables of integer exponents by name, zero exponents left out, so a speed is
+	`{ length = 1, time = -1 }` and a plain number is `{}`. Any name is a dimension; `time`, `length`, `memory`,
+	`mass`, `temperature`, `angle`, `current`, `amount` and `luminousIntensity` are the base dimensions [MetricUnit] has units for, and derived ones such as force
+	and energy are products of those. The named combinations, such as `"speed"`, are in [MetricUnitKinds].
+
+	```lua
+	MetricUnitDimensionUtils.combine({ length = 1 }, { time = 1 }, -1) -- { length = 1, time = -1 }
+	MetricUnitDimensionUtils.describe({ length = 1, time = -1 }) -- "length/time"
+	```
+
+	@class MetricUnitDimensionUtils
+]=]
+
+local MetricUnitDimensionUtils = {}
+
+--[=[
+	Integer exponents keyed by dimension name, with zero exponents left out.
+
+	@type Dimensions { [string]: number }
+	@within MetricUnitDimensionUtils
+]=]
+export type Dimensions = { [string]: number }
+
+--[=[
+	No dimensions: a plain number's, and what `combine` returns when every exponent cancels.
+
+	@prop NONE Dimensions
+	@within MetricUnitDimensionUtils
+]=]
+MetricUnitDimensionUtils.NONE = table.freeze({}) :: Dimensions
+
+--[=[
+	The exponents of `a` plus `sign` times those of `b`: a product when `sign` is 1, a quotient when it is -1.
+
+	@param a Dimensions
+	@param b Dimensions
+	@param sign number -- 1 or -1
+	@return Dimensions
+]=]
+function MetricUnitDimensionUtils.combine(a: Dimensions, b: Dimensions, sign: number): Dimensions
+	local result: Dimensions = table.clone(a)
+	for name, exponent in b do
+		local total = (result[name] or 0) + sign * exponent
+		if total == 0 then
+			result[name] = nil
+		else
+			result[name] = total
+		end
+	end
+	return table.freeze(result)
+end
+
+--[=[
+	The exponents of `a` times `factor`, erroring if any is not a whole number.
+
+	@param a Dimensions
+	@param factor number
+	@return Dimensions
+]=]
+function MetricUnitDimensionUtils.scale(a: Dimensions, factor: number): Dimensions
+	local result: Dimensions = {}
+	for name, exponent in a do
+		local scaled = exponent * factor
+		if scaled ~= math.floor(scaled) then
+			error(
+				string.format(
+					"MetricUnit: %s to the power %s has a fractional exponent",
+					MetricUnitDimensionUtils.describe(a),
+					tostring(factor)
+				),
+				3
+			)
+		end
+		if scaled ~= 0 then
+			result[name] = scaled
+		end
+	end
+	return table.freeze(result)
+end
+
+--[=[
+	Whether `a` and `b` have the same exponents.
+
+	@param a Dimensions
+	@param b Dimensions
+	@return boolean
+]=]
+function MetricUnitDimensionUtils.equal(a: Dimensions, b: Dimensions): boolean
+	if a == b then
+		return true
+	end
+	for name, exponent in a do
+		if b[name] ~= exponent then
+			return false
+		end
+	end
+	for name in b do
+		if a[name] == nil then
+			return false
+		end
+	end
+	return true
+end
+
+--[=[
+	Whether `value` is a table of whole-number exponents keyed by name, none of them zero.
+
+	@param value any
+	@return boolean
+]=]
+function MetricUnitDimensionUtils.isDimensions(value: any): boolean
+	if type(value) ~= "table" then
+		return false
+	end
+	for name, exponent in value do
+		if
+			type(name) ~= "string"
+			or type(exponent) ~= "number"
+			or exponent == 0
+			or exponent ~= math.floor(exponent)
+		then
+			return false
+		end
+	end
+	return true
+end
+
+--[=[
+	A readable formula for `dimensions`: "time", "length/time", "1/time", "length^2" or "dimensionless".
+
+	@param dimensions Dimensions
+	@return string
+]=]
+function MetricUnitDimensionUtils.describe(dimensions: Dimensions): string
+	local over: { string } = {}
+	local under: { string } = {}
+	for _, name in MetricUnitDimensionUtils._sortedNames(dimensions) do
+		local exponent = dimensions[name]
+		local power = math.abs(exponent)
+		local part = if power == 1 then name else name .. "^" .. tostring(power)
+		table.insert(if exponent > 0 then over else under, part)
+	end
+	if #over == 0 and #under == 0 then
+		return "dimensionless"
+	end
+	local text = if #over == 0 then "1" else table.concat(over, "·")
+	for _, part in under do
+		text ..= "/" .. part
+	end
+	return text
+end
+
+function MetricUnitDimensionUtils._sortedNames(dimensions: Dimensions): { string }
+	local names: { string } = {}
+	for name in dimensions do
+		table.insert(names, name)
+	end
+	table.sort(names)
+	return names
+end
+
+return table.freeze(MetricUnitDimensionUtils)

package/src/Shared/Definitions/MetricUnitDimensionUtils.spec.lua

@@ -0,0 +1,49 @@
+--!strict
+--[[
+	@class MetricUnitDimensionUtils.spec.lua
+]]
+
+local require = require(script.Parent.loader).load(script)
+
+local Jest = require("Jest")
+local MetricUnitDimensionUtils = require("MetricUnitDimensionUtils")
+
+local describe = Jest.Globals.describe
+local expect = Jest.Globals.expect
+local it = Jest.Globals.it
+
+describe("MetricUnitDimensionUtils", function()
+	it("combines exponents, dropping zeros, frozen", function()
+		local speed = MetricUnitDimensionUtils.combine({ length = 1 }, { time = 1 }, -1)
+		expect(speed).toEqual({ length = 1, time = -1 })
+		expect(table.isfrozen(speed)).toBe(true)
+		expect(MetricUnitDimensionUtils.combine(speed, { time = 1 }, 1)).toEqual({ length = 1 })
+		expect(MetricUnitDimensionUtils.combine(speed, speed, -1)).toEqual(MetricUnitDimensionUtils.NONE)
+	end)
+
+	it("takes any name as a dimension", function()
+		local people = MetricUnitDimensionUtils.combine({ people = 1 }, { length = 1 }, -2)
+		expect(MetricUnitDimensionUtils.describe(people)).toBe("people/length^2")
+	end)
+
+	it("scales exponents, erroring on a fractional one", function()
+		expect(MetricUnitDimensionUtils.scale({ length = 2 }, 0.5)).toEqual({ length = 1 })
+		expect(function()
+			MetricUnitDimensionUtils.scale({ length = 1 }, 0.5)
+		end).toThrow("length to the power 0.5 has a fractional exponent")
+	end)
+
+	it("describes dimensions as a formula", function()
+		expect(MetricUnitDimensionUtils.describe(MetricUnitDimensionUtils.NONE)).toBe("dimensionless")
+		expect(MetricUnitDimensionUtils.describe({ time = -1 })).toBe("1/time")
+		expect(MetricUnitDimensionUtils.describe({ length = 2, mass = 1 })).toBe("length^2·mass")
+	end)
+
+	it("tells equal dimensions apart, and valid ones from others", function()
+		expect(MetricUnitDimensionUtils.equal({ length = 1, time = -1 }, { time = -1, length = 1 })).toBe(true)
+		expect(MetricUnitDimensionUtils.equal({ length = 1 }, { length = 1, time = -1 })).toBe(false)
+		expect(MetricUnitDimensionUtils.isDimensions({ length = 2 })).toBe(true)
+		expect(MetricUnitDimensionUtils.isDimensions({ length = 0.5 })).toBe(false)
+		expect(MetricUnitDimensionUtils.isDimensions({ length = 0 })).toBe(false)
+	end)
+end)

package/src/Shared/Definitions/MetricUnitKinds.lua

@@ -0,0 +1,237 @@
+--!strict
+--[=[
+	The named kinds of measurement, such as `"length"` and `"speed"`: each a set of dimensions, absolute or a
+	difference. [MetricUnit.GetKind], [MetricUnit.isKind] and [MetricUnit.expect] take these names. The dimension
+	functions they are built from are in [MetricUnitDimensionUtils].
+
+	```lua
+	MetricUnitKinds.SPEED -- { length = 1, time = -1 }
+	MetricUnitKinds.fromName("speed") -- { length = 1, time = -1 }, false
+	MetricUnitKinds.getKind({ temperature = 1 }, true) -- "temperature"
+	```
+
+	@class MetricUnitKinds
+]=]
+
+local require = require(script.Parent.loader).load(script)
+
+local MetricUnitDimensionUtils = require("MetricUnitDimensionUtils")
+
+local MetricUnitKinds = {}
+
+type Dimensions = MetricUnitDimensionUtils.Dimensions
+
+--[=[
+	A kind's name. `"temperature"` is an absolute temperature and `"temperatureDifference"` a difference between two.
+	`"time"` is a span of time and `"instant"` a point in time, measured from an epoch the caller chooses. `"none"` is
+	a plain, dimensionless number.
+
+	@type KindName "none" | "time" | "length" | "area" | "volume" | "memory" | "mass" | "rate" | "speed" | "acceleration" | "force" | "energy" | "power" | "pressure" | "density" | "dataRate" | "temperature" | "temperatureDifference" | "instant" | "angle" | "angularVelocity" | "angularAcceleration" | "current" | "charge" | "voltage" | "resistance" | "conductance" | "capacitance" | "inductance" | "magneticFlux" | "magneticFluxDensity" | "amount" | "luminousIntensity" | "solidAngle" | "luminousFlux" | "illuminance" | "absorbedDose" | "catalyticActivity" | "molarMass" | "molarConcentration" | "fuelEconomy"
+	@within MetricUnitKinds
+]=]
+export type KindName =
+	"none"
+	| "time"
+	| "length"
+	| "area"
+	| "volume"
+	| "memory"
+	| "mass"
+	| "rate"
+	| "speed"
+	| "acceleration"
+	| "force"
+	| "energy"
+	| "power"
+	| "pressure"
+	| "density"
+	| "dataRate"
+	| "temperature"
+	| "temperatureDifference"
+	| "instant"
+	| "angle"
+	| "angularVelocity"
+	| "angularAcceleration"
+	| "current"
+	| "charge"
+	| "voltage"
+	| "resistance"
+	| "conductance"
+	| "capacitance"
+	| "inductance"
+	| "magneticFlux"
+	| "magneticFluxDensity"
+	| "amount"
+	| "luminousIntensity"
+	| "solidAngle"
+	| "luminousFlux"
+	| "illuminance"
+	| "absorbedDose"
+	| "catalyticActivity"
+	| "molarMass"
+	| "molarConcentration"
+	| "fuelEconomy"
+
+MetricUnitKinds.TIME = table.freeze({ time = 1 }) :: Dimensions
+MetricUnitKinds.LENGTH = table.freeze({ length = 1 }) :: Dimensions
+MetricUnitKinds.MEMORY = table.freeze({ memory = 1 }) :: Dimensions
+MetricUnitKinds.MASS = table.freeze({ mass = 1 }) :: Dimensions
+MetricUnitKinds.TEMPERATURE = table.freeze({ temperature = 1 }) :: Dimensions
+MetricUnitKinds.ANGLE = table.freeze({ angle = 1 }) :: Dimensions
+MetricUnitKinds.CURRENT = table.freeze({ current = 1 }) :: Dimensions
+MetricUnitKinds.AMOUNT = table.freeze({ amount = 1 }) :: Dimensions
+MetricUnitKinds.LUMINOUS_INTENSITY = table.freeze({ luminousIntensity = 1 }) :: Dimensions
+
+local function times(a: Dimensions, b: Dimensions): Dimensions
+	return MetricUnitDimensionUtils.combine(a, b, 1)
+end
+
+local function per(a: Dimensions, b: Dimensions): Dimensions
+	return MetricUnitDimensionUtils.combine(a, b, -1)
+end
+
+MetricUnitKinds.AREA = times(MetricUnitKinds.LENGTH, MetricUnitKinds.LENGTH)
+MetricUnitKinds.VOLUME = times(MetricUnitKinds.AREA, MetricUnitKinds.LENGTH)
+MetricUnitKinds.RATE = per(MetricUnitDimensionUtils.NONE, MetricUnitKinds.TIME)
+MetricUnitKinds.SPEED = per(MetricUnitKinds.LENGTH, MetricUnitKinds.TIME)
+MetricUnitKinds.ACCELERATION = per(MetricUnitKinds.SPEED, MetricUnitKinds.TIME)
+MetricUnitKinds.FORCE = times(MetricUnitKinds.MASS, MetricUnitKinds.ACCELERATION)
+MetricUnitKinds.ENERGY = times(MetricUnitKinds.FORCE, MetricUnitKinds.LENGTH)
+MetricUnitKinds.POWER = per(MetricUnitKinds.ENERGY, MetricUnitKinds.TIME)
+MetricUnitKinds.PRESSURE = per(MetricUnitKinds.FORCE, MetricUnitKinds.AREA)
+MetricUnitKinds.DENSITY = per(MetricUnitKinds.MASS, MetricUnitKinds.VOLUME)
+MetricUnitKinds.DATA_RATE = per(MetricUnitKinds.MEMORY, MetricUnitKinds.TIME)
+MetricUnitKinds.ANGULAR_VELOCITY = per(MetricUnitKinds.ANGLE, MetricUnitKinds.TIME)
+MetricUnitKinds.ANGULAR_ACCELERATION = per(MetricUnitKinds.ANGULAR_VELOCITY, MetricUnitKinds.TIME)
+MetricUnitKinds.CHARGE = times(MetricUnitKinds.CURRENT, MetricUnitKinds.TIME)
+MetricUnitKinds.VOLTAGE = per(MetricUnitKinds.POWER, MetricUnitKinds.CURRENT)
+MetricUnitKinds.RESISTANCE = per(MetricUnitKinds.VOLTAGE, MetricUnitKinds.CURRENT)
+MetricUnitKinds.CONDUCTANCE = per(MetricUnitKinds.CURRENT, MetricUnitKinds.VOLTAGE)
+MetricUnitKinds.CAPACITANCE = per(MetricUnitKinds.CHARGE, MetricUnitKinds.VOLTAGE)
+MetricUnitKinds.MAGNETIC_FLUX = times(MetricUnitKinds.VOLTAGE, MetricUnitKinds.TIME)
+MetricUnitKinds.INDUCTANCE = per(MetricUnitKinds.MAGNETIC_FLUX, MetricUnitKinds.CURRENT)
+MetricUnitKinds.MAGNETIC_FLUX_DENSITY = per(MetricUnitKinds.MAGNETIC_FLUX, MetricUnitKinds.AREA)
+MetricUnitKinds.SOLID_ANGLE = times(MetricUnitKinds.ANGLE, MetricUnitKinds.ANGLE)
+MetricUnitKinds.LUMINOUS_FLUX = times(MetricUnitKinds.LUMINOUS_INTENSITY, MetricUnitKinds.SOLID_ANGLE)
+MetricUnitKinds.ILLUMINANCE = per(MetricUnitKinds.LUMINOUS_FLUX, MetricUnitKinds.AREA)
+MetricUnitKinds.ABSORBED_DOSE = per(MetricUnitKinds.ENERGY, MetricUnitKinds.MASS)
+MetricUnitKinds.CATALYTIC_ACTIVITY = per(MetricUnitKinds.AMOUNT, MetricUnitKinds.TIME)
+MetricUnitKinds.MOLAR_MASS = per(MetricUnitKinds.MASS, MetricUnitKinds.AMOUNT)
+MetricUnitKinds.MOLAR_CONCENTRATION = per(MetricUnitKinds.AMOUNT, MetricUnitKinds.VOLUME)
+MetricUnitKinds.FUEL_ECONOMY = per(MetricUnitKinds.LENGTH, MetricUnitKinds.VOLUME)
+
+type NamedKind = { name: KindName, dimensions: Dimensions, absolute: boolean }
+
+local NAMED_KINDS_IN_LOOKUP_ORDER: { NamedKind } = {
+	{ name = "none", dimensions = MetricUnitDimensionUtils.NONE, absolute = false },
+	{ name = "time", dimensions = MetricUnitKinds.TIME, absolute = false },
+	{ name = "length", dimensions = MetricUnitKinds.LENGTH, absolute = false },
+	{ name = "area", dimensions = MetricUnitKinds.AREA, absolute = false },
+	{ name = "volume", dimensions = MetricUnitKinds.VOLUME, absolute = false },
+	{ name = "memory", dimensions = MetricUnitKinds.MEMORY, absolute = false },
+	{ name = "mass", dimensions = MetricUnitKinds.MASS, absolute = false },
+	{ name = "rate", dimensions = MetricUnitKinds.RATE, absolute = false },
+	{ name = "speed", dimensions = MetricUnitKinds.SPEED, absolute = false },
+	{ name = "acceleration", dimensions = MetricUnitKinds.ACCELERATION, absolute = false },
+	{ name = "force", dimensions = MetricUnitKinds.FORCE, absolute = false },
+	{ name = "energy", dimensions = MetricUnitKinds.ENERGY, absolute = false },
+	{ name = "power", dimensions = MetricUnitKinds.POWER, absolute = false },
+	{ name = "pressure", dimensions = MetricUnitKinds.PRESSURE, absolute = false },
+	{ name = "density", dimensions = MetricUnitKinds.DENSITY, absolute = false },
+	{ name = "dataRate", dimensions = MetricUnitKinds.DATA_RATE, absolute = false },
+	{ name = "temperature", dimensions = MetricUnitKinds.TEMPERATURE, absolute = true },
+	{ name = "temperatureDifference", dimensions = MetricUnitKinds.TEMPERATURE, absolute = false },
+	{ name = "instant", dimensions = MetricUnitKinds.TIME, absolute = true },
+	{ name = "angle", dimensions = MetricUnitKinds.ANGLE, absolute = false },
+	{ name = "angularVelocity", dimensions = MetricUnitKinds.ANGULAR_VELOCITY, absolute = false },
+	{ name = "angularAcceleration", dimensions = MetricUnitKinds.ANGULAR_ACCELERATION, absolute = false },
+	{ name = "current", dimensions = MetricUnitKinds.CURRENT, absolute = false },
+	{ name = "charge", dimensions = MetricUnitKinds.CHARGE, absolute = false },
+	{ name = "voltage", dimensions = MetricUnitKinds.VOLTAGE, absolute = false },
+	{ name = "resistance", dimensions = MetricUnitKinds.RESISTANCE, absolute = false },
+	{ name = "conductance", dimensions = MetricUnitKinds.CONDUCTANCE, absolute = false },
+	{ name = "capacitance", dimensions = MetricUnitKinds.CAPACITANCE, absolute = false },
+	{ name = "inductance", dimensions = MetricUnitKinds.INDUCTANCE, absolute = false },
+	{ name = "magneticFlux", dimensions = MetricUnitKinds.MAGNETIC_FLUX, absolute = false },
+	{ name = "magneticFluxDensity", dimensions = MetricUnitKinds.MAGNETIC_FLUX_DENSITY, absolute = false },
+	{ name = "amount", dimensions = MetricUnitKinds.AMOUNT, absolute = false },
+	{ name = "luminousIntensity", dimensions = MetricUnitKinds.LUMINOUS_INTENSITY, absolute = false },
+	{ name = "solidAngle", dimensions = MetricUnitKinds.SOLID_ANGLE, absolute = false },
+	{ name = "luminousFlux", dimensions = MetricUnitKinds.LUMINOUS_FLUX, absolute = false },
+	{ name = "illuminance", dimensions = MetricUnitKinds.ILLUMINANCE, absolute = false },
+	{ name = "absorbedDose", dimensions = MetricUnitKinds.ABSORBED_DOSE, absolute = false },
+	{ name = "catalyticActivity", dimensions = MetricUnitKinds.CATALYTIC_ACTIVITY, absolute = false },
+	{ name = "molarMass", dimensions = MetricUnitKinds.MOLAR_MASS, absolute = false },
+	{ name = "molarConcentration", dimensions = MetricUnitKinds.MOLAR_CONCENTRATION, absolute = false },
+	{ name = "fuelEconomy", dimensions = MetricUnitKinds.FUEL_ECONOMY, absolute = false },
+}
+
+local KIND_BY_NAME: { [string]: NamedKind } = {}
+for _, kind in NAMED_KINDS_IN_LOOKUP_ORDER do
+	KIND_BY_NAME[kind.name] = table.freeze(kind)
+end
+table.freeze(NAMED_KINDS_IN_LOOKUP_ORDER)
+table.freeze(KIND_BY_NAME)
+
+--[=[
+	The dimensions a [KindName] stands for, or the table given, and whether it names an absolute value. Errors on an
+	unknown name.
+
+	@param kind KindName | Dimensions
+	@return Dimensions
+	@return boolean -- whether the name is of an absolute value
+]=]
+function MetricUnitKinds.fromName(kind: KindName | Dimensions): (Dimensions, boolean)
+	if type(kind) == "table" then
+		return kind, false
+	end
+	local named = KIND_BY_NAME[kind]
+	if not named then
+		error(string.format("MetricUnit: no kind named %q", tostring(kind)), 3)
+	end
+	return named.dimensions, named.absolute
+end
+
+--[=[
+	The [KindName] of `dimensions`, absolute or a difference, or nil for a compound without a name.
+
+	```lua
+	MetricUnitKinds.getKind({ length = 1, time = -1 }, false) -- "speed"
+	MetricUnitKinds.getKind({ temperature = 1 }, true) -- "temperature"
+	MetricUnitKinds.getKind({ length = 4 }, false) -- nil
+	```
+
+	@param dimensions Dimensions
+	@param absolute boolean
+	@return KindName?
+]=]
+function MetricUnitKinds.getKind(dimensions: Dimensions, absolute: boolean): KindName?
+	for _, kind in NAMED_KINDS_IN_LOOKUP_ORDER do
+		if kind.absolute == absolute and MetricUnitDimensionUtils.equal(kind.dimensions, dimensions) then
+			return kind.name
+		end
+	end
+	return nil
+end
+
+--[=[
+	What a value of `dimensions` is, absolute or a difference: "absolute temperature", "temperature difference",
+	"instant", "length/time".
+
+	@param dimensions Dimensions
+	@param absolute boolean
+	@return string
+]=]
+function MetricUnitKinds.describeKind(dimensions: Dimensions, absolute: boolean): string
+	local formula = MetricUnitDimensionUtils.describe(dimensions)
+	if absolute and MetricUnitDimensionUtils.equal(dimensions, MetricUnitKinds.TIME) then
+		return "instant"
+	elseif absolute then
+		return "absolute " .. formula
+	elseif MetricUnitDimensionUtils.equal(dimensions, MetricUnitKinds.TEMPERATURE) then
+		return formula .. " difference"
+	end
+	return formula
+end
+
+return table.freeze(MetricUnitKinds)

package/src/Shared/Definitions/MetricUnitKinds.spec.lua

@@ -0,0 +1,51 @@
+--!strict
+--[[
+	@class MetricUnitKinds.spec.lua
+]]
+
+local require = require(script.Parent.loader).load(script)
+
+local Jest = require("Jest")
+local MetricUnitDimensionUtils = require("MetricUnitDimensionUtils")
+local MetricUnitKinds = require("MetricUnitKinds")
+
+local describe = Jest.Globals.describe
+local expect = Jest.Globals.expect
+local it = Jest.Globals.it
+
+describe("MetricUnitKinds", function()
+	it("derives every kind from the base dimensions", function()
+		expect(MetricUnitKinds.DENSITY).toEqual({ mass = 1, length = -3 })
+		expect(MetricUnitKinds.POWER).toEqual({ mass = 1, length = 2, time = -3 })
+		expect(MetricUnitKinds.VOLTAGE).toEqual({ mass = 1, length = 2, time = -3, current = -1 })
+		expect(MetricUnitKinds.RESISTANCE).toEqual({ mass = 1, length = 2, time = -3, current = -2 })
+		expect(MetricUnitKinds.CAPACITANCE).toEqual({ mass = -1, length = -2, time = 4, current = 2 })
+		expect(MetricUnitKinds.MAGNETIC_FLUX_DENSITY).toEqual({ mass = 1, time = -2, current = -1 })
+	end)
+
+	it("reads a kind's dimensions and absoluteness from its name", function()
+		expect((MetricUnitKinds.fromName("dataRate"))).toEqual({ memory = 1, time = -1 })
+		expect((MetricUnitKinds.fromName("none"))).toBe(MetricUnitDimensionUtils.NONE)
+		expect(select(2, MetricUnitKinds.fromName("temperature"))).toBe(true)
+		expect(select(2, MetricUnitKinds.fromName("temperatureDifference"))).toBe(false)
+		expect((MetricUnitKinds.fromName({ length = 4 }))).toEqual({ length = 4 })
+		expect(function()
+			MetricUnitKinds.fromName("velocity" :: any)
+		end).toThrow('no kind named "velocity"')
+	end)
+
+	it("names the kind of a set of dimensions", function()
+		expect(MetricUnitKinds.getKind(MetricUnitKinds.SPEED, false)).toBe("speed")
+		expect(MetricUnitKinds.getKind(MetricUnitKinds.TEMPERATURE, true)).toBe("temperature")
+		expect(MetricUnitKinds.getKind(MetricUnitKinds.TIME, true)).toBe("instant")
+		expect(MetricUnitKinds.getKind(MetricUnitDimensionUtils.NONE, false)).toBe("none")
+		expect(MetricUnitKinds.getKind({ length = 4 }, false)).toBeNil()
+	end)
+
+	it("describes a kind, absolute or a difference", function()
+		expect(MetricUnitKinds.describeKind(MetricUnitKinds.TEMPERATURE, true)).toBe("absolute temperature")
+		expect(MetricUnitKinds.describeKind(MetricUnitKinds.TEMPERATURE, false)).toBe("temperature difference")
+		expect(MetricUnitKinds.describeKind(MetricUnitKinds.TIME, true)).toBe("instant")
+		expect(MetricUnitKinds.describeKind(MetricUnitKinds.SPEED, false)).toBe("length/time")
+	end)
+end)

package/src/Shared/Formatting/MetricUnitDisplayUnitUtils.lua

@@ -0,0 +1,129 @@
+--!strict
+--[=[
+	Which unit to display a value in when the caller does not name one: for each dimension, the units to choose from
+	by size (`2500 m` displays as `2.5 km`), the time unit a rate is displayed per, and the SI symbols for an unnamed
+	compound. Used by [MetricUnitFormatUtils].
+
+	@class MetricUnitDisplayUnitUtils
+]=]
+
+local require = require(script.Parent.loader).load(script)
+
+local MetricUnitDefinitions = require("MetricUnitDefinitions")
+local MetricUnitDimensionUtils = require("MetricUnitDimensionUtils")
+local MetricUnitSystem = require("MetricUnitSystem")
+local MetricUnitSystems = require("MetricUnitSystems")
+
+local MetricUnitDisplayUnitUtils = {}
+
+type UnitDefinition = MetricUnitDefinitions.UnitDefinition
+
+local PER_UNIT_IDS_SHORTEST_FIRST: { string } = table.freeze({ "second", "minute", "hour", "day", "year" })
+local perUnitsShortestFirst: { UnitDefinition }? = nil
+
+local SI_BASE_UNIT_SYMBOLS: { [string]: string } = table.freeze({
+	time = "s",
+	length = "m",
+	memory = "B",
+	mass = "kg",
+	temperature = "K",
+	angle = "rad",
+	current = "A",
+	amount = "mol",
+	luminousIntensity = "cd",
+}) :: any
+
+--[=[
+	The units a value of `dimensions` is shown in, largest first, from `system` and its fallbacks ([MetricUnitSystems.METRIC]
+	by default), or nil when none lists the dimension. An absolute value is shown on a scale people read, °C rather
+	than kelvin, where the system has one.
+
+	@param dimensions Dimensions
+	@param system MetricUnitSystem?
+	@param absolute boolean?
+	@return { UnitDefinition }?
+]=]
+function MetricUnitDisplayUnitUtils.getDisplayUnits(
+	dimensions: MetricUnitDimensionUtils.Dimensions,
+	system: MetricUnitSystem.MetricUnitSystem?,
+	absolute: boolean?
+): { UnitDefinition }?
+	return MetricUnitSystem.GetDisplayUnits(system or MetricUnitSystems.METRIC, dimensions, absolute)
+end
+
+--[=[
+	The largest unit on `units` that `amount` base units fills at least once, the smallest when it fills none, or
+	[MetricUnitDisplayUnitUtils.getBaseUnit] when `amount` is zero.
+
+	@param amount number
+	@param units { UnitDefinition }
+	@return UnitDefinition
+]=]
+function MetricUnitDisplayUnitUtils.pickDisplayUnit(amount: number, units: { UnitDefinition }): UnitDefinition
+	if amount == 0 then
+		return MetricUnitDisplayUnitUtils.getBaseUnit(units)
+	end
+	for _, unit in units do
+		if math.abs(amount / unit.factor) >= 1 then
+			return unit
+		end
+	end
+	return units[#units]
+end
+
+--[=[
+	The unit on `units` that is one SI base unit, or the smallest when none is.
+
+	@param units { UnitDefinition }
+	@return UnitDefinition
+]=]
+function MetricUnitDisplayUnitUtils.getBaseUnit(units: { UnitDefinition }): UnitDefinition
+	for _, unit in units do
+		if unit.factor == 1 then
+			return unit
+		end
+	end
+	return units[#units]
+end
+
+--[=[
+	The shortest time unit that a rate of `amount` per second reaches at least once over, or a year when none does.
+
+	@param amount number -- per second
+	@return UnitDefinition
+]=]
+function MetricUnitDisplayUnitUtils.pickDisplayPerUnit(amount: number): UnitDefinition
+	local units = MetricUnitDisplayUnitUtils._perUnitsShortestFirst()
+	for _, unit in units do
+		if math.abs(amount * unit.factor) >= 1 then
+			return unit
+		end
+	end
+	return units[#units]
+end
+
+function MetricUnitDisplayUnitUtils._perUnitsShortestFirst(): { UnitDefinition }
+	local found = perUnitsShortestFirst
+	if found then
+		return found
+	end
+	local units: { UnitDefinition } = {}
+	for _, id in PER_UNIT_IDS_SHORTEST_FIRST do
+		table.insert(units, (assert(MetricUnitDefinitions.getUnit(id), id)))
+	end
+	local frozen = table.freeze(units)
+	perUnitsShortestFirst = frozen
+	return frozen
+end
+
+--[=[
+	The SI base unit symbol for a dimension name, such as `"m"` for `"length"`, or the name itself when it has none.
+
+	@param name string
+	@return string
+]=]
+function MetricUnitDisplayUnitUtils.getBaseSymbol(name: string): string
+	return SI_BASE_UNIT_SYMBOLS[name] or name
+end
+
+return table.freeze(MetricUnitDisplayUnitUtils)