@torthu/metrify

Helpers for working with measurements and units in TypeScript.

Metrify is a work in progress. API changes may occur.

Installation

npm i --save @torthu/metrify

pnpm add @torthu/metrify

Usage

Measurements and conversions

Metrify provides a collection of measurement classes that contains conversion factors.

Note: the conversions are not exhaustive, meaning that the build in conversion factors are not enough to convert between all units.

You can create a new Measurement by passing a tuple with a value and a unit.

import { Mass } from "@torthu/metrify";

// I have 1 kg
const oneKG = new Mass([1, "kg"]);

// But I want to know how many pounds that is
console.log(oneKG.to("lb"));

Arithmetic operations

Metrify ships with simple arithmetic functions.

import { Distance, add } from "@torthu/metrify";

const distanceA = new Distance([1, "m"]);
const distanceB = new Distance([1, "km"]);
const distanceC = add(distanceA, distanceB);

console.log(distanceC.to("ft")); // 3284.12

Metrify will try to the best of its ability to do Measurement conversions when doing arithmetic operations.

Please note that these conversions are not complete or perfect.

const distance = new Distance([1, "m"]);
const area = multiply(distance, distance); // Area
const volume = multiply(distance, area); // Volume

If Metrify does not recognize the result type of an arithmetic operation, it will return a MeasurementTuple:

const distance = new Distance([1, "m"]);
const time = new Time([1, "s"]);

const weirdNewUnit = multiply(distance, time); // [number, "m*s"]

Metrify is expandable, you can add new Measurement classes:

import type { Measurement, Dimension } from "@torthu/metrify";
import { register } from "@torthu/metrify";

class MyCustomMeasurement implements Measurement {
	static readonly dimensions: Dimensions = { m: 1, s: 1 };
	static readonly siUnit: string = "m*s";

	type = "MS";
}

register(MyCustomMeasurement);

const distance = new Distance([1, "m"]);
const time = new Time([1, "s"]);

const weirdNewUnit = multiply(distance, time); // MyCustomMeasurement

You can also replace Measurement (i.e if you need larger or smaller measurements) classes. See examples/BigDistance.ts for an example of how to do this.

Advanced concepts

Dimensions

Every measurement class declares a static dimensions property of type Record<string, number>. The keys are SI base unit symbols and the values are their exponents, encoding the physical dimensionality of the quantity:

Measurement	Key	SI Base Quantity
Length	m	meter
Mass	kg	kilogram
Time	s	second
Electric current	A	ampere
Temperature	K	kelvin
Amount of substance	mol	mole
Luminous intensity	cd	candela
Angle	rad	radian

For example:

Measurement	Dimensions	Conceptual meaning
Distance	{ m: 1 }	length
Area	{ m: 2 }	length^2
Speed	{ m: 1, s: -1 }	length / time
Force	{ kg: 1, m: 1, s: -2 }	mass * length / time^2

When you multiply two measurements, Metrify adds the exponents of their dimensions. When you divide, it subtracts them. The resulting dimensions are then looked up in the registry to find the matching measurement class:

// multiply: adds exponents
// Distance { m: 1 } * Area { m: 2 } → { m: 3 } → Volume

// divide: subtracts exponents
// Distance { m: 1 } / Time { s: 1 } → { m: 1, s: -1 } → Speed

If no registered class matches the resulting dimensions, a raw tuple [number, string] is returned instead. You can register your own measurement classes to handle custom dimension combinations.

Glossary

Measurement	Symbol	Name
Acceleration	m/s2	meter per second squared
Acceleration	ft/s2	foot per second squared
Acceleration	gforce	standard gravity
AmountOfSubstance	mol	mole
AmountOfSubstance	mmol	millimole
AmountOfSubstance	μmol	micromole
Angle	deg	degree
Angle	rad	radian
Angle	turn	turn
Angle	gon	gradian
Area	km2	square kilometer
Area	m2	square meter
Area	cm2	square centimeter
Area	mm2	square millimeter
Area	ha	hectare
Area	ft2	square foot
Area	ac	acre
Area	mi2	square mile
Density	kg/m3	kilogram per cubic meter
Density	g/cm3	gram per cubic centimeter
Density	lb/ft3	pound per cubic foot
Distance	km	kilometer
Distance	m	meter
Distance	dm	decimeter
Distance	cm	centimeter
Distance	mm	millimeter
Distance	in	inch
Distance	ft	foot
Distance	yd	yard
Distance	mi	mile
ElectricCurrent	A	ampere
ElectricCurrent	mA	milliampere
ElectricCurrent	μA	microampere
ElectricResistance	ohm	Ω
ElectricResistance	kohm	kiloΩ
ElectricResistance	Mohm	megaΩ
ElectricResistance	mohm	milliΩ
Energy	J	joule
Energy	kJ	kilojoule
Energy	cal	calorie
Energy	kcal	kilocalorie
Energy	Wh	watt-hour
Energy	kWh	kilowatt-hour
Energy	BTU	British thermal unit
Force	N	newton
Force	kN	kilonewton
Force	lbf	pound-force
Force	dyn	dyne
Frequency	Hz	hertz
Frequency	kHz	kilohertz
Frequency	MHz	megahertz
Frequency	GHz	gigahertz
Frequency	rpm	revolutions per minute
LuminousIntensity	cd	candela
LuminousIntensity	mcd	millicandela
LuminousIntensity	kcd	kilocandela
Mass	kg	kilogram
Mass	g	gram
Mass	mg	milligram
Mass	t	tonne
Mass	oz	ounce
Mass	lb	pound
Power	W	watt
Power	kW	kilowatt
Power	MW	megawatt
Power	hp	horsepower
Pressure	Pa	pascal
Pressure	kPa	kilopascal
Pressure	bar	bar
Pressure	atm	atmosphere
Pressure	psi	pound per square inch
Speed	m/s	meter per second
Speed	km/h	kilometer per hour
Speed	mph	mile per hour
Speed	knot	knot
Speed	ft/s	foot per second
Temperature	K	kelvin
Temperature	C	degree Celsius
Temperature	F	degree Fahrenheit
Time	h	hour
Time	min	minute
Time	s	second
Time	ms	millisecond
Voltage	V	volt
Voltage	mV	millivolt
Voltage	kV	kilovolt
Volume	L	liter
Volume	mL	milliliter
Volume	m3	cubic meter
Volume	cm3	cubic centimeter
Volume	gal	gallon
Volume	qt	quart
Volume	pt	pint
Volume	cup	cup
Volume	floz	fluid ounce