@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 |