This project is part of the @thi.ng/umbrella monorepo.

• About
  • Unit definitions
  • Predefined units
    • Acceleration
    • Angle
    • Area
    • Data
    • Density
    • Electric current
    • Energy
    • Force
    • Frequency
    • Length
    • Luminous intensity
    • Mass
    • Parts per notation
    • Power
    • Pressure
    • Speed
    • Substance
    • Temperature
    • Time
    • Volume
  • Creating & deriving units
    • Using standard metric prefixes
    • Unit combinators
  • Unit conversions
  • Quantities
    • Constants
• Status
• Installation
• Dependencies
• API
• Authors
• License

Extensible SI unit creation, conversions, quantities & calculations (incl. ~170 predefined units & constants).

All unit definitions, quantities & conversions are based on the SI unit system & concepts described here:

• https://en.wikipedia.org/wiki/International_System_of_Units
• https://en.wikipedia.org/wiki/SI_base_unit
• https://en.wikipedia.org/wiki/SI_derived_unit
• https://en.wikipedia.org/wiki/Coherence_(units_of_measurement)
• https://en.wikipedia.org/wiki/Metric_prefix

The overall conversion approach is inspired & partially based on:

• Frink
• @g7s/unit

Each unit is defined via a 7-dimensional vector representing individual exponents for each of the SI base unit dimensions, in order:

Dimensionless units (e.g. radian, byte) are supported too and represented by a vector with all dimensions set to zero.

Additionally, we also define a scale factor and zero offset for each unit, with most dimensions' base units usually using a factor of 1 and no offset.

For example, here's how we can define kilograms and meters:

// kilogram, SI dimension 0
const KG = coherent(0);
// { dim: [ 1, 0, 0, 0, 0, 0, 0 ], scale: 1, offset: 0, coherent: true }

// meters, SI dimension 1
const M = coherent(1);
// { dim: [ 0, 1, 0, 0, 0, 0, 0 ], scale: 1, offset: 0, coherent: true }

// kelvin, SI dimension 4 (here without syntax sugar)
const K = unit(4, 1, 0, true);
// { dim: [ 0, 0, 0, 0, 1, 0, 0 ], scale: 1, offset: 0, coherent: true }

// fahrenheit, SI dim 4 with custom scale factor and zero offset
const F = unit(4, 1 / 1.8, 459.67 / 1.8);
// { dim: [ 0, 0, 0, 0, 1, 0, 0 ],  scale: 0.5555, offset: 255.3722, coherent: false }

More complex units like electrical resistance (e.g. ohm) are based on more than a single dimension:

// ohm = volt / ampere
div(V, A)
// { dim: [ 1, 2, -3, -2, 0, 0,  0 ], scale: 1, offset: 0, coherent: true }

This dimension vector represents the unit definition for (see SI derived units):

Ω = kg⋅m²⋅s⁻³⋅A⁻²

Btw. The formatSI() function can be used to format a unit's dimension vector:

formatSI(div(V, A));
// "kg·m2·s-3·A-2"

The following units are provided as "builtins", here grouped by dimension:

https://en.wikipedia.org/wiki/Parts-per_notation

Existing coherent units can be prefixed to produce derived versions:

// define micrometer (also available as preset)
prefix("µ", "m")
// { dim: [ 0, 1, 0, 0, 0, 0, 0 ], scale: 0.000001, offset: 0, coherent: false }

// define kKhz
prefix("k", Hz);
// { dim: [ 0, 0, -1, 0, 0, 0, 0 ], scale: 1000, offset: 0, coherent: false }

The following combinators can be used to derive scaled and/or more complex units (or quantities) in multiple SI dimensions:

• div(a, b): derives a new unit via the division of the given units
• mul(a, b): derives a new unit as the product of the given units
• pow(u, k): raises given unit to power k (e.g. meter ⇒ square meter)
• reciprocal(u): Creates reciprocal of given unit (e.g. Hz ⇒ 1/second)

// acceleration (meter per second squared)
const m_s2 = div(m, pow(s, 2));
// { dim: [ 0, 1, -2, 0, 0, 0,  0 ], scale: 1, offset: 0, coherent: false }

// define kilowatt-hour (also available as preset)
const kWh = mul(prefix("k","W"), "h");
// { dim: [ 1, 2, -2, 0, 0, 0, 0 ], scale: 3600000, offset: 0, coherent: false }

// define `word` as 16 bits
const word = mul(bit, 16);
// { dim: [ 0, 0, 0, 0, 0, 0, 0 ], scale: 16, offset: 0, coherent: false }

// Hz = 1/s
const Hz = reciprocal(s);
// { dim: [ 0, 0, -1, 0, 0, 0, 0 ], scale: 1, offset: 0, coherent: false }

Units (and quantities) can be converted using convert(). Only units with compatible (incl. reciprocal) dimensions can be converted, otherwise an error will be thrown. On the other hand, all dimensionless units can be converted to other dimensionless units (even if it would be semantic nonsense).

Units can be specified in various ways:

// convert from km/h to mph using unit names
convert(100, "km/h", "mph");
// 62.13711922373341

// or using predefined unit constants directly
convert(60, mph, km_h);
// 96.56063999999998

// or using anonymous units (meter/second ⇒ yard/hour)
convert(1, "m/s", div(yd, h));
// 3937.007874015749

// convert into opposite direction (meter/second  ⇒ second/meter)
convert(10, "m/s", reciprocal("m/s"));
// 0.1

Another example using dimensionless units (here angles, arc second ⇒ radian) to compute the distance of 10 arcsec on the earth surface (in meters):

// earth radius in meters
// (also available as quantity EARTH_RADIUS, see section below)
const R = 6371000;

convert(10, "arcsec", "rad") * R;
// 308.87479623488537

The library also supports defining quantities, i.e. certain finite amounts of a given unit. These can be a number or vector-based and can be used for calculations & conversions using the above mentioned polymorphic functions: div(), mul(), reciprocal() and convert().

Quantities are created via quantity() which acts as factory function for a thin Quantity class wrapper. The latter also implements the standard IDeref interface to obtain the unwrapped amount (though it only should be used for dimensionless quantities). Use convert() otherwise!

// (also available as preset)
const speedOfLight = quantity(299792458, "m/s");

// compute wavelength of a WiFi signal in millimeters
convert(div(speedOfLight, quantity(2.4,"GHz")), "mm");
// 124.9135

Some examples using vector quantities:

// DIN A4 paper size (also available as preset)
const A4 = quantity([210, 297], "mm");

// convert paper size to inches
convert(A4, "in");
// [ 8.2677, 11.6929 ]

// or calculate pixel dimensions @ 300 dpi
// the result of this product is dimensionless,
// so we use the NONE preset as target unit...
convert(mul(A4, quantity(300, "dpi")), NONE)
// [ 2480.314960629921, 3507.8740157480315 ]

// alternatively, dimensionless units can be deref'd directly
mul(A4, quantity(300, "dpi")).deref()
// [ 2480.314960629921, 3507.8740157480315 ]

When combining different quantities, their units do not need to be the same:

// compute 10 mm x 2 inch and convert to square centimeter
convert(mul(quantity(10, "mm"), quantity(2, "in")), "cm2")
// 5.08

The following constants are provided (more to come):

• ⁽¹⁾ - all paper sizes are also available as landscape presets (using _LANDSCAPE as suffix).

Densities of selected materials:

BETA - possibly breaking changes forthcoming

Search or submit any issues for this package

yarn add @thi.ng/units

ES module import:

<script type="module" src="https://cdn.skypack.dev/@thi.ng/units"></script>

Skypack documentation

For Node.js REPL:

const units = await import("@thi.ng/units");

Package sizes (brotli'd, pre-treeshake): ESM: 4.77 KB

• @thi.ng/api
• @thi.ng/checks
• @thi.ng/equiv
• @thi.ng/errors

Generated API docs

• Karsten Schmidt

If this project contributes to an academic publication, please cite it as:

@misc{thing-units,
  title = "@thi.ng/units",
  author = "Karsten Schmidt",
  note = "https://thi.ng/units",
  year = 2021
}

© 2021 - 2023 Karsten Schmidt // Apache License 2.0