Awesome

convert-units

A handy utility for converting between quantities in different units.

Installation

npm install convert-units --save

# beta builds are also available with
npm install convert-units@beta --save

Usage

convert-units has a simple chained API that is easy to read. It can also be configured with the measures that are packaged with it or custom measures.

The code snippet below shows everything needed to get going:

// `allMeasures` includes all the measures packaged with this library
import configureMeasurements from 'convert-units';
import allMeasures from 'convert-units/definitions/all';

const convert = configureMeasurements(allMeasures);

It's also possible to limit the measures configured. This allows for smaller packages when using a bundler like webpack or rollup:

import configureMeasurements from 'convert-units';
import volume from 'convert-units/definitions/volume';

/*
  `configureMeasurements` is a closure that accepts a directory
  of measures and returns a factory function (`convert`) that uses
  only those measures.
*/
const convert = configureMeasurements({
    volume,
    mass,
    length,
});

Converting between units in a measure:

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

Converting between systems is handled automatically (imperial to metric in this case):

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

Attempting to convert between measures will result in an error:

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

To convert a unit to another unit within the same measure with the smallest value above 1:

convert(12000).from('mm').toBest();
// { val: 12, unit: 'm', ... }

Note: The toBest method is subjective and does not work for all measures.

If a better value is not found, then from unit is returned. This is also the case for zero:

convert(1).from('mm').toBest();
// { val: 1, unit: 'mm', ... }

convert(0).from('mm').toBest();
// { val: 0, unit: 'mm', ... }

Exclude units to get different results:

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

The best is always the smallest number above 1. If the value is a negative number, the best is always the largest number below -1. The cut off number of either 1 or -1 can be changed to get different results:

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

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

// by default the system of the origin is used, the `system` option overwrites this behaviour
convert(254).from('mm').toBest({ system: 'imperial' }); // ('mm' is metric)
// { val: 10, unit: 'in', plural: 'Inches' }            // ('in' is imperial)

List all available measures:

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

const differentConvert = configureMeasurements({
    volume,
    mass,
    length,
    area,
});
differentConvert().measures();
// [ 'length', 'mass', 'volume', 'area' ]

List all units that a given unit can be converted to:

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

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

List all units that belong to a measure:

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

List all configured 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' ];

Get a detailed description of a unit:

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

List detailed descriptions of all units:

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

List detailed descriptions of all units for a measure:

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

Custom Measures

To create a custom measure, it's best to start with an plain object. The key itself will be used as the measure's name. In the example below, the measure's name is "customMeasure".