InkUnits

Smart unit conversion engine written in TypeScript. InkUnits has no external dependencies and is very small in size.

InkUnits can understand compound units and figure out the right conversion factor.

Installation

Using yarn:

yarn add inkunits

with npm:

npm i inkunits --save

Usage

Import the conversion function:

import { convert } from 'inkunits'

Then use the fluent API:

convert(45).from('N/cm2').to('lbf/ft2')

9398.67401

Another example:

convert(1000).from('N*m/s').to('lbf*ft/min')

44253.19098

To account for possible conversion errors between incompatible units:

try {
    convert(45).from('N').to('ft')
} catch(error: Error) {
    console.log(error.message)
}

The code above would print to the console the following error message:

Cannot convert from N to ft

Supported units

InkUnits now supports the following units and every possible combination between them:

Time

Universal System

• ms: milliseconds
• s: seconds
• min: minutes
• h: hours
• day: days
• week: weeks
• month: months
• year: years

Angle

Universal System

• rad: radians
• deg: degrees

Length

International System

• mm: millimiters
• cm: centimeters
• dm: decimeters
• m: meters
• dam: decameters
• hm: hectometers
• km: kilometers

US Customary System

• mi: miles
• ft: feet
• in: inches

Mass

International System

• mg: milligrams
• cg: centigrams
• dg: decigrams
• g: grams
• dag: decagrams
• hg: hectograms
• kg: kilograms

US Customary System

• oz: ounzes
• lb: pounds

Force

International System

• N: Newtons
• kN: kilonewtons
• MN: meganewtons
• GN: giganewtowns

US Customary System

• lbf: pound of force

Unit Conversion Factors

The conversion factors are configured in src/factors.json. These factors are given in groups. Time, length or force are examples of groups.

Each group in the factors.json file follow the following format:

"<group_name>": {
    "systems": [
        ...
    ],
    "system_conversion_factors": [
      {
        "from": "international",
        "to": "us",
        "factor": ...
      },
      {
        "from": "us",
        "to": "international",
        "factor": ...
      }
    ]
}

Each group can define conversion factors for different unit systems. InkUnits works with three unit systems:

• International (m, cm, N, kg...)
• US Customary (ft, in, lbf...)
• Universal

The universal system of units is used when a particular unit group is used regardless of the system. For example, angles are given in radians both in the International and US systems.

The "system_conversion_factors" provides the factors required to convert units from one system to another and viceversa.

Factors

Each system has the following structure for the conversion factors:

{
    "name": "<system_name>",
    "factors": {
        ...
    }
}

Every unit system's factors must include a reference unit which factor is 1.