TypeScript Units and Measurement

@adam-rocska/units-and-measurement is a TypeScript library for representing measurements, converting between known units, and comparing or combining compatible measurements without repeating conversion code.

It supports four measurement shapes:

• String measurements such as "15px".
• Tuple measurements such as [15, "px"].
• Object measurements such as { value: 15, unit: "px" }.
• Dimension measurements such as inches(11), with same-dimension conversion properties like .cm, .m, and .ft.

Installation

pnpm add @adam-rocska/units-and-measurement

npm install @adam-rocska/units-and-measurement

The package targets Node.js 20 and newer and ships TypeScript declarations.

Quick Start

import {dimension} from "@adam-rocska/units-and-measurement";
import {add, areEqual} from "@adam-rocska/units-and-measurement/operations";
import {
  centimeters,
  inches,
  meters,
  type Length,
} from "@adam-rocska/units-and-measurement/length";

const pageWidth: Length = inches(8.5);
const margin = centimeters(2);

console.log(pageWidth.cm.value);
console.log(pageWidth.cm.unit);

const usableWidth = add(pageWidth, margin);

if (usableWidth !== undefined && dimension.isMeasurement(usableWidth)) {
  console.log(dimension.toFixed(usableWidth.cm, 2).value);
}

if (areEqual(meters(1), centimeters(100))) {
  console.log("Same length.");
}

Package Entry Points

Use the root package for generic measurement helpers and representation namespaces:

import {
  object,
  string,
  tuple,
  unit,
  value,
} from "@adam-rocska/units-and-measurement";

const asString = string.measurement(12, "px");
const asTuple = tuple.measurement(12, "px");
const asObject = object.measurement(12, "px");

console.log(value(asString), unit(asTuple), asObject.value);

Use the operations submodule for arithmetic, comparison, proportionality, and common-unit conversion:

import {add, greaterThan, proportion, toCommonUnit} from "@adam-rocska/units-and-measurement/operations";
import {centimeters, meters} from "@adam-rocska/units-and-measurement/length";

const total = add(meters(2), centimeters(50));
const normalized = toCommonUnit(meters(2), centimeters(50));
const ratio = proportion(meters(2), centimeters(50));

console.log(total);
console.log(normalized);
console.log(ratio);
console.log(greaterThan(meters(2), centimeters(50)));

Use dimension submodules when you want ready-made unit conversion factories:

import {kilometers, meters} from "@adam-rocska/units-and-measurement/length";
import {celsius, fahrenheit} from "@adam-rocska/units-and-measurement/temperature";

console.log(kilometers(1).m.value);
console.log(meters(1609.34).mi.value);
console.log(celsius(0).K.value);
console.log(fahrenheit(32)["°C"].value);

Built-In Dimensions

Each dimension submodule exports:

• A symbol union type, such as LengthSymbol.
• A symbol list, such as lengthSymbols.
• A symbol predicate, such as isLengthSymbol.
• A dimension measurement type, such as Length.
• The dimension object, such as length.
• Named factory aliases, such as meters, inches, and centimeters.

Available dimension entry points:

| Import path suffix | Dimension object | Measurement type | | ------------------ | ---------------- | ---------------- | | /acceleration | acceleration | Acceleration | | /angle | angle | Angle | | /area | area | Area | | /concentration-mass | concentrationMass | ConcentrationMass | | /dispersion | dispersion | Dispersion | | /duration | duration | Duration | | /electric-charge | electricCharge | ElectricCharge | | /electric-current | electricCurrent | ElectricCurrent | | /electric-potential-difference | electricPotentialDifference | ElectricPotentialDifference | | /electric-resistance | electricResistance | ElectricResistance | | /energy | energy | Energy | | /frequency | frequency | Frequency | | /illuminance | illuminance | Illuminance | | /information | information | Information | | /length | length | Length | | /mass | mass | Mass | | /power | power | Power | | /pressure | pressure | Pressure | | /speed | speed | Speed | | /temperature | temperature | Temperature | | /volume | volume | Volume |

More detail is available in docs/dimensions.md.

Custom Dimensions

Custom dimensions can be created from conversion rules. The conversion base is the unit whose coefficient is 1.

import {dimension as d} from "@adam-rocska/units-and-measurement";

type CurrencySymbol = "USD" | "cent";

const currency = d.dimension<CurrencySymbol>({
  USD: d.linearConversion(1),
  cent: d.linearConversion(0.01),
});

const invoiceTotal = currency.USD(19.99);

console.log(invoiceTotal.cent.value);

Documentation

• Usage guide
• Dimension reference
• Development guide
• Contribution guide

Development

pnpm install
pnpm test
pnpm typecheck
pnpm lint
pnpm check
pnpm build

pnpm check runs linting, TypeScript checks, and package export validation.