@bstoots/convert-units

3.0.3 • Public • Published

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

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

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

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

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

• 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'

• C
• F
• K
• R

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

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

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

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

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

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

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

• lx
• ft-cd

• ppm
• ppb
• ppt
• ppq

• V
• mV
• kV

• A
• mA
• kA

• W
• mW
• kW
• MW
• GW

• VA
• mVA
• kVA
• MVA
• GVA

• VAR
• mVAR
• kVAR
• MVAR
• GVAR

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

• VARh
• mVARh
• kVARh
• MVARh
• GVARh

• deg
• arcmin
• arcsec

• c
• mC
• μC
• nC
• pC

• N
• kN
• lbf

• 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.

Package Sidebar

Install

`npm i @bstoots/convert-units`

5

3.0.3

MIT

148 kB

77