convert-units

A handy utility for converting between quantities in different units.

Installation

npm i @bstoots/convert-units

Usage

convert-units has a simple chained API that is easy to read.

Here's how you move between the metric units for volume:

var convert = require('@bstoots/convert-units')

convert(1).from('l').to('ml')
// 1000

Jump from imperial to metric units the same way:

convert(1).from('lb').to('kg')
// 0.4536... (tested to 4 significant figures)

Just be careful not to ask for an impossible conversion:

convert(1).from('oz').to('fl-oz')
// throws -- you can't go from mass to volume!

You can ask convert-units to select the best unit for you. You can also optionally explicitly exclude orders of magnitude or specify a cut off number for selecting the best representation.

convert(12000).from('mm').toBest()
// 12 Meters (the smallest unit with a value above 1)

convert(12000).from('mm').toBest({ exclude: ['m'] })
// 1200 Centimeters (the smallest unit excluding meters)

convert(900).from('mm').toBest({ cutOffNumber: 10 });
// 90 Centimeters (the smallest unit with a value equal to or above 10)

convert(1000).from('mm').toBest({ cutOffNumber: 10 })
// 100 Centimeters (the smallest unit with a value equal to or above 10)

You can get a list of the measurement types supported with .measures

convert().measures()
// [ 'length', 'mass', 'volume' ]

If you ever want to know the possible conversions for a unit, just use .possibilities

convert().from('l').possibilities()
// [ 'ml', 'l', 'tsp', 'Tbs', 'fl-oz', 'cup', 'pnt', 'qt', 'gal' ]

convert().from('kg').possibilities()
// [ 'mcg', 'mg', 'g', 'kg', 'oz', 'lb' ]

You can also get the possible conversions for a measure:

convert().possibilities('mass')
// [ 'mcg', 'mg', 'g', 'kg', 'oz', 'lb', 'mt', 't' ]

You can also get the all the available units:

convert().possibilities()
// [ 'mm', 'cm', 'm', 'in', 'ft-us', 'ft', 'mi', 'mcg', 'mg', 'g', 'kg', 'oz', 'lb', 'mt', 't', 'ml', 'l', 'tsp', 'Tbs', 'fl-oz', 'cup', 'pnt', 'qt', 'gal', 'ea', 'dz' ];

To get a detailed description of a unit, use describe

convert().describe('kg')
/*
  {
    abbr: 'kg'
  , measure: 'mass'
  , system: 'metric'
  , singular: 'Kilogram'
  , plural: 'Kilograms'
  }
*/

To get detailed descriptions of all units, use list.

convert().list()
/*
  [{
    abbr: 'kg'
  , measure: 'mass'
  , system: 'metric'
  , singular: 'Kilogram'
  , plural: 'Kilograms'
  }, ...]
*/

You can also get detailed descriptions of all units for a measure:

convert().list('mass')
/*
  [{
    abbr: 'kg'
  , measure: 'mass'
  , system: 'metric'
  , singular: 'Kilogram'
  , plural: 'Kilograms'
  }, ...]
*/

Supported Units

Length

• mm
• cm
• m
• km
• in
• yd
• ft-us
• ft
• fathom
• mi
• nMi

Area

• mm2
• cm2
• m2
• ha
• km2
• in2
• ft2
• ac
• mi2

Mass

• mcg
• mg
• g
• kg
• oz
• lb
• mt
• t

Volume

• mm3
• cm3
• ml
• l
• kl
• m3
• km3
• tsp
• Tbs
• in3
• fl-oz
• cup
• pnt
• qt
• gal
• ft3
• yd3

Volume Flow Rate

• mm3/s
• cm3/s
• ml/s
• cl/s
• dl/s
• l/s
• l/min
• l/h
• kl/s
• kl/min
• kl/h
• m3/s
• m3/min
• m3/h
• km3/s
• tsp/s
• Tbs/s
• in3/s
• in3/min
• in3/h
• fl-oz/s
• fl-oz/min
• fl-oz/h
• cup/s
• pnt/s
• pnt/min
• pnt/h
• qt/s
• gal/s
• gal/min
• gal/h
• ft3/s
• ft3/min
• ft3/h
• yd3/s
• yd3/min
• yd3/h'

Temperature

• C
• F
• K
• R

Time

• ns
• mu
• ms
• s
• min
• h
• d
• week
• month
• year

Frequency

• Hz
• mHz
• kHz
• MHz
• GHz
• THz
• rpm
• deg/s
• rad/s

Speed

• m/s
• km/h
• m/h
• knot
• ft/s

Pace

• s/m
• min/km
• s/ft
• min/km

Pressure

• Pa
• hPa
• kPa
• MPa
• bar
• torr
• psi
• ksi

Digital (Binary)

• ib
• Kib
• Mib
• Gib
• Tib
• iB
• KiB
• MiB
• GiB
• TiB
• PiB
• EiB
• ZiB
• YiB

Digital (Decimal)

• b
• Kb
• Mb
• Gb
• Tb
• B
• KB
• MB
• GB
• TB
• PB
• EB
• ZB
• YB

Illuminance

• lx
• ft-cd

Parts-Per

• ppm
• ppb
• ppt
• ppq

Voltage

• V
• mV
• kV

Current

• A
• mA
• kA

Power

• W
• mW
• kW
• MW
• GW

Apparent Power

• VA
• mVA
• kVA
• MVA
• GVA

Reactive Power

• VAR
• mVAR
• kVAR
• MVAR
• GVAR

Energy

• Wh
• mWh
• kWh
• MWh
• GWh
• J
• kJ

Reactive Energy

• VARh
• mVARh
• kVARh
• MVARh
• GVARh

Angle

• deg
• rad
• grad
• arcmin
• arcsec

Charge

• c
• mC
• μC
• nC
• pC

Force

• N
• kN
• lbf

Acceleration

• g (g-force)
• m/s2

Want More?

Adding new measurement sets is easy. Take a look at lib/definitions to see how it's done.