convert-units / convert-units

An elegant way to convert quantities between different units.

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

Code example:

const measure = {
  customMeasure: {},
};

Next step is to create the measure's systems. A system is a collection of related units. Here are some examples of some common systems: metric, imperial, SI, bits, bytes, etc. You don't need to use one of these systems for your measure. In the example below, there are 3 systems defined: A, B, C.

Code example:

const measure = {
  customMeasure: {
    systems: {
      A: {},
      B: {},
      C: {},
    }
  },
};

Now the measure is ready to define some units. The first unit that needs to be defined for each system is the base unit. The base unit is like all other units except that it's the unit used to convert between systems and every other unit in the system will be configured to convert directly to it. Below is an example of a base unit for the A system.

Code example:

const measure = {
  customMeasure: {
    systems: {
      A: {
        a: {  // the name of the unit (commonly an abbreviation)
          name: {  // human friendly names for the unit
            singular: 'a',
            plural: 'as',
          },
        }
      },
      // ignoring C & B for now
    }
  },
};

Each unit also needs to an to_anchor property. to_anchor holds a number which represents the factor needed to go from another unit in the system to the base unit. In the case of the a unit, the value will be 1. The value for all base units in every system should to be 1 because if you convert 5 a to a the result should be 5 a. This is because the value of to_anchor is multiplied with the value of the unit being converted from. So in this case, 5 * 1 = 5.

Code example:

const measure = {
  customMeasure: {
    systems: {
      A: {
        a: {
          name: {
            singular: 'a',
            plural: 'as',
          },
          to_anchor: 1,
        }
      },
      // ignoring C & B for now
    }
  },
};

Adding a second measure to the A measure looks exactly the same as the a unit except the to_anchor value will be different. If the unit is supposed to be larger than the base then the to_anchor value needs to be greater than 1. For example, the new unit ah should be a factor of 10 larger than the base. This would mean that 1 ah equals 10 a. To make sure this assumption is correct multiply the to_anchor by the unit, 5 ah * 10 = 50 a.

Code example:

const measure = {
  customMeasure: {
    systems: {
      A: {
        ah: {  // new unit, ah
          name: {
            singular: 'ah',
            plural: 'ahs',
          },
          to_anchor: 1e1,  // = 10 ^ 1 = 10
        },
        a: {
          name: {
            singular: 'a',
            plural: 'as',
          },
          to_anchor: 1,
        }
      },
      // ignoring C & B for now
    },
  },
};

If the unit should be smaller than the base unit then the to_anchor value should be less than 1 and greater than 0. With that said, the new unit al should have a to_anchor value of 0.1. This would mean that 10 al would equal 1 a.

Code example:

const measure = {
  customMeasure: {
    systems: {
      A: {
        ah: {  // new unit, ah
          name: {
            singular: 'ah',
            plural: 'ahs',
          },
          to_anchor: 1e1,  // = 10 ^ 1 = 10
        },
        a: {
          name: {
            singular: 'a',
            plural: 'as',
          },
          to_anchor: 1,
        }
        al: {  // new unit, al
          name: {
            singular: 'al',
            plural: 'als',
          },
          to_anchor: 1e-1,  // = 10 ^ -1 = 0.1
        },
      },
      // ignoring C & B for now
    },
  },
};

There is one more option, anchor_shift, it can be defined on a unit if it requires to be shifted after the conversion. If al had a anchor_shift of 5 then 10 al to a would look like, 10 * 0.1 - 5 = -4 a. If the shift needs to go in the opposite direction then it should be a negative number. Typically, measures and units that use the anchor_shift only need to be shifted. If that is the desired effect then setting to_anchor to 1 for each unit will achieve that. To see a real world example, check out the temperature measure in the definitions folder.

Code example:

const measure = {
  customMeasure: {
    systems: {
      A: {
        ah: {  // new unit, ah
          name: {
            singular: 'ah',
            plural: 'ahs',
          },
          to_anchor: 1e1,  // = 10 ^ 1 = 10
        },
        a: {
          name: {
            singular: 'a',
            plural: 'as',
          },
          to_anchor: 1,
        }
        al: {  // new unit, al
          name: {
            singular: 'al',
            plural: 'als',
          },
          to_anchor: 1e-1,  // = 10 ^ -1 = 0.1
          anchor_shift: 5,
        },
      },
      // ignoring C & B for now
    }
  },
};

At this point if the custom measure only needs one system then it's done! However, if it requires more than one system, an extra step is required. In the example code below, the previously ignored systems C and B have been defined to look exactly like the A system.

Code example:

const measure = {
  customMeasure: {
    systems: {
      A: {
        ah: {
          name: {
            singular: 'ah',
            plural: 'ahs',
          },
          to_anchor: 1e1,
        },
        a: {
          name: {
            singular: 'a',
            plural: 'as',
          },
          to_anchor: 1,
        },
        al: {
          name: {
            singular: 'al',
            plural: 'als',
          },
          to_anchor: 1e-1,
        },
      },
      B: {
        bh: {
          name: {
            singular: 'bh',
            plural: 'bhs',
          },
          to_anchor: 1e1,
        },
        b: {
          name: {
            singular: 'b',
            plural: 'bs',
          },
          to_anchor: 1,
        },
        bl: {
          name: {
            singular: 'bl',
            plural: 'bls',
          },
          to_anchor: 1e-1,
        },
      },
      C: {
        ch: {
          name: {
            singular: 'ch',
            plural: 'chs',
          },
          to_anchor: 1e1,
        },
        c: {
          name: {
            singular: 'c',
            plural: 'cs',
          },
          to_anchor: 1,
        },
        cl: {
          name: {
            singular: 'cl',
            plural: 'cls',
          },
          to_anchor: 1e-1,
        },
      },
    },
  }
};

The measure now has three systems, A, B, and C. To define how each system can be converted to the other, anchors will needs to be defined for each possible conversion. To start, add the key anchors to the customMeasure object:

Code example:

const measure = {
  customMeasure: {
    systems: {
      // ...
    },
    anchors: {},
  }
};

Then just like for the systems object, add a key for each system with it's value being an empty object:

Code example:

const measure = {
  customMeasure: {
    systems: {
      // ...
    },
    anchors: {
      A: {},
      B: {},
      C: {},
    },
  }
};

In each of those empty objects, add keys for the other systems which their values being an empty object. The measure should look like the code snippet below:

Code example:

const measure = {
  customMeasure: {
    systems: {
      // ...
    },
    anchors: {
      A: {  // A to B or C
        B: {},
        C: {},
      },
      B: {  // B to A or C
        A: {},
        C: {},
      },
      C: {  // C to A or B
        A: {},
        B: {},
      },
    },
  }
};

When converting, for example, 1 a to bl, the code can perform a simple lookup here, anchors.A.B. If instead the conversion is from 10 c to ah then the lookup would be, anchors.C.A. At this point how to convert from one system to the next hasn't been defined yet; that will be the next and final step in creating a new measure.

Each system pair needs to either defined a ratio or a transform function. If a ratio is defined then it's multiplied by the base unit to convert it to the target system's base unit. If transform is defined, the function is called with the value of the best unit. It's value is used as the base unit of the target system. The transform function should return a number.

Note: If both ratio and transform are defined then the ratio will be used and the transform function will be ignored. If nether are defined, the conversion will throw an error.

Code example:

const measure = {
  customMeasure: {
    systems: {
      // ...
    },
    anchors: {
      A: {  // A to B or C
        B: {
          ratio: 2,
        },
        C: {
          ratio: 3,
        },
      },
      B: {  // B to A or C
        A: {
          ratio: 1 / 2,
        },
        C: {
          ratio: 3 / 2,
        },
      },
      C: {  // C to A or B
        A: {
          // example of using a transform function
          // This would be the same as ratio: 1 / 3
          transform: value => value * 1 / 3,
        },
        B: {
          transform: value => value * 2 / 3,
        },
      },
    },
  }
};

With the above example, converting 10 cl to ah would result in 0.0333 (rounded).

Here is the complete measure:

const measure = {
  customMeasure: {
    systems: {
      A: {
        ah: {
          name: {
            singular: 'ah',
            plural: 'ahs',
          },
          to_anchor: 1e1,
        },
        a: {
          name: {
            singular: 'a',
            plural: 'as',
          },
          // to_anchor: The factor used to reach the base unit
          // The base unit should have a to_anchor value of 1
          // Eg. 1 a -> al = 1a * 1e-1 (to_anchor of al) = 10 al
          to_anchor: 1,
        },
        al: {
          name: {
            singular: 'al',
            plural: 'als',
          },
          to_anchor: 1e-1,
        },
      },
      B: {
        bh: {
          name: {
            singular: 'bh',
            plural: 'bhs',
          },
          to_anchor: 1e1,
        },
        b: {
          name: {
            singular: 'b',
            plural: 'bs',
          },
          to_anchor: 1,
        },
        bl: {
          name: {
            singular: 'bl',
            plural: 'bls',
          },
          to_anchor: 1e-1,
        },
      },
      C: {
        ch: {
          name: {
            singular: 'ch',
            plural: 'chs',
          },
          to_anchor: 1e1,
        },
        c: {
          name: {
            singular: 'c',
            plural: 'cs',
          },
          to_anchor: 1,
        },
        cl: {
          name: {
            singular: 'cl',
            plural: 'cls',
          },
          to_anchor: 1e-1,
        },
      },
    },
    anchors: {
      A: {
        // unit a -> unit b
        B: {
          ratio: 2,
        },
        // unit a -> unit c
        C: {
          ratio: 3,
        },
      },
      B: {
        // unit b -> unit a
        A: {
          ratio: 1 / 2,
        },
        // unit b -> unit c
        C: {
          ratio: 3 / 2,
        },
      },
      C: {
        // unit c -> unit a
        A: {
          ratio: 1 / 3,
        },
        // unit c -> unit b
        B: {
          ratio: 2 / 3,
        },
      },
    },
  }
};

const convert = configureMeasurements(measure);
convert(1).from('a').to('bl')
// 20

Pseudo code that shows the maths involved when converting a unit

// a -> bl
let v = 1  // 1 a
let a_to_anchor = 1  // systems.A.a.to_anchor
let r = v * a_to_anchor
// r = 1 a
let ratio = 2  // anchors.A.B.ratio
r *= ratio
// r = 2 b
let bl_to_anchor = 1e-1  // systems.B.bl.to_anchor
r /= b_to_anchor
// r = 20 bl

Extending Existing Measures

Since measure definitions are plain JS objects, additional units can be added, removed, and changed.

Example of extending the `length` measure

import configureMeasurements, {
  Measure
} from 'convert-units';

import
  length, {
  LengthSystems,
  LengthUnits,
} from "convert-units/definitions/length"

type NewLengthUnits = LengthUnits | 'px';
const DPI = 96;
const extendedLength: Measure<LengthSystems, NewLengthUnits> = {
  systems: {
    metric: {
      ...length.systems.metric,
      px: {
        name: {
          singular: 'Pixel',
          plural: 'Pixels',
        },
        to_anchor: 0.0254 / DPI,
      },
    },
    imperial: {
      ...length.systems.imperial,
    },
  },
  anchors: {
    ...length.anchors,
  },
};

const convert = configureMeasurements<'length', LengthSystems, NewLengthUnits>(
  { length: extendedLength }
);

convert(4).from('cm').to('px');
// 151.18110236220474

Migrating from v2 to v3+

This only applies if moving from <=2.3.4 to >=3.x.

index.js

import convert from 'convert-units';

convert(1).from('m').to('mm');
convert(1).from('m').to('ft');

The code above could be changed to match the following:

index.js

import convert from './convert';  // defined below

convert(1).from('m').to('mm');
convert(1).from('m').to('ft');

convert.js

import configureMeasurements from 'convert-units';
import allMeasures from 'convert-units/definitions/all';  

export default configureMeasurements(allMeasures);

Typescript

The library provides types for all packaged mesasures:

import configureMeasurements from 'convert-units';

import length, {
  LengthSystems,
  LengthUnits,
} from "convert-units/definitions/length"

import area, {
  AreaSystems,
  AreaUnits,
} from "convert-units/definitions/area"

// Measures: The names of the measures being used
type Measures = 'length' | 'area';
// Systems: The systems being used across all measures
type Systems = LengthSystems | AreaSystems;
// Units: All the units across all measures and their systems
type Units = LengthUnits | AreaUnits;

const convert = configureMeasurements<Measures, Systems, Units>({
  length,
  area,
});

convert(4).from('m').to('cm');
// 400

This also allows for IDE tools to highlight issues before running the application:

import configureMeasurements from 'convert-units';

import length, {
  LengthSystems,
  LengthUnits,
} from "convert-units/definitions/length"

import area, {
  AreaSystems,
  AreaUnits,
} from "convert-units/definitions/area"

// Measures: The names of the measures being used
type Measures = 'length' | 'area';
// Systems: The systems being used across all measures
type Systems = LengthSystems | AreaSystems;
// Units: All the units across all measures and their systems
type Units = LengthUnits | AreaUnits;

const convert = configureMeasurements<Measures, Systems, Units>({
  length,
  area,
});

convert(4).from('wat').to('cm');
// Typescript will warm that the unit `wat` does not exist because it's not a member of the `Units` type defined above.

Types for the allMeasures object are also provided:

import configureMeasurements from 'convert-units';

import allMeasures, {
  AllMeasures,
  AllMeasuresSystems,
  AllMeasuresUnits,
} from 'convert-units/definitions/all';

const convertAll = configureMeasurements<
  AllMeasures,
  AllMeasuresSystems,
  AllMeasuresUnits
>(allMeasures);

convertAll(4).from('m2').to('cm2');
// 400000

Request Measures & Units

All new measures and additional units are welcome! Take a look at src/definitions to see some examples.

Packaged Units

Length

* nm * μm * 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 * st * t

Volume

* mm3 * cm3 * ml * l * kl * Ml * Gl * 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 * mph * knot * ft/s * in/h * mm/h

Torque

* Nm * lbf-ft

Pace

* s/m * min/km * s/ft * min/mi

Pressure

* Pa * hPa * kPa * MPa * bar * torr * mH2O * mmHg * psi * ksi

Digital

* bit * byte * kB * MB * GB * TB * KiB * MiB * GiB * TiB

Illuminance

* lx * ft-cd

Parts-Per

* ppm * ppb * ppt * ppq

Voltage

* V * mV * kV

Current

* A * mA * kA

Power

* W * mW * kW * MW * GW * PS * Btu/s * ft-lb/s * hp

Apparent Power

* VA * mVA * kVA * MVA * GVA

Reactive Power

* VAR * mVAR * kVAR * MVAR * GVAR

Energy

* Ws * Wm * Wh * mWh * kWh * MWh * GWh * J * kJ * MJ * GJ

Reactive Energy

* VARh * mVARh * kVARh * MVARh * GVARh

Angle

* deg * rad * grad * arcmin * arcsec

Charge

* c * mC * μC * nC * pC

Force

* N * kN * lbf * kgf

Acceleration

* g (g-force) * m/s2

Pieces

* pcs * bk-doz * cp * doz-doz * doz * gr-gr * gros * half-dozen * long-hundred * ream * scores * sm-gr * trio

License

Copyright (c) 2013-2017 Ben Ng and Contributors, http://benng.me

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

convert-units's Issues

Joules to BTU?

Has there been any conversation on measurements of thermal energy?

Error in volume conversion

You've mis-identified "US" values as "imperial".

3.7 litres to the US gallon, whilst 4.5 litres to the imperial gallon. This is quite a big issue.

Area conversions

Is there any area conversions (m^2, hectare, ft^2, acres etc.)?

toBest() returns a hardcoded English string

toBest is super useful unless you need to internationalize the application using that library.

I would like to propose a version of toBest that returns an object like so ...

{value: number, unit: string}

Not only does this make it easier for i18n but it also allows me to use the converted value and the units separately. For instance, I might want to style my units differently from the value.

Again, this seems like a straightforward change so I'm more than willing to submit a PR.

hours and minutes

is it possible to convert ms to hour: minutes? currently I only see the hour conversion (h)

[NFR] inches of mercury (inHg)

Would it be possible to add a conversion for inches of mercury (inHg) to this awesome lib?

krm and msk have the same singular and plural in description

When you call convert().describe('krm') it will return:

{  
   abbr:"krm",
   measure:"volume",
   system:"metric",
   singular:"Matsked",
   plural:"Matskedar"
}

I think the singular (Matsked) and plural (Matskedar) values are for msk and wrongly used for krm.

Change litre symbol

The SI accepted symbol for litre is L or l. The ltr abbreviation is common, but incorrect.

mph/kmh

I was not able to find speed units, would someone create speed units?

^punisher

Error in Pressure Module

Looks like you may have an error in your Pressure module.

The anchor unit for the imperial system is marked as "psi". But the psi to_anchor is 1/1000 instead of 1, while the to_anchor for "ksi" is 1. Since to_anchor is the multiplier to convert to the anchor unit, the anchor unit should always have a ratio of 1.

Feature Request - Create blood glucose (mmo/l - mg/dL) & hba1c (mmol-mol) - (percent)

Just a another set of units you could add 👍

Support binary and decimal digital conversions

Hello, I would like to add support for decimal digital conversions in addition to the existing binary conversions. Decimal seems to be much more common when dealing with storage capacities. Unfortunately it appears the current digital conversion definition is already using the base 10 / metric / decimal names and abbreviations but defining its calculation in base 2.

For example, currently 1 megabyte (MB) is defined as 1048576 (1024^2) bytes but the unit should be the lesser used mebibyte (MiB). Megabyte should be defined as 1000000 (1000^2) bytes to allow for both sets of units to coexist in the conversion library without too much hair-pulling.

Making this change would require a new major version as I would like to see the API changed to make B, KB, MB, etc use the decimal values and use iB, KiB, MiB, etc for binary calculations.

Import only a certain type of units

If I want to convert between units of mass, it would be cool to be able to include only that functionality in order to avoid bloating the codebase when developing an SPA.

For example:

import { mass as convertMass } from 'convert-units';

Add support for alternative unit names and abbreviations

Suggested interface: add an alternates property to the name definition.

This would work in tandem with the lookup feature requested in issue #98 and fixed in PR #99 .

See PR #101 for working support with tests:

imperial = {
, Tbs: {
    name: {
      singular: 'Tablespoon'
    , plural: 'Tablespoons'
    , alternates: ['tbsp']
    }
  , to_anchor: 1/2
  }
, 
...

Best unit function

Hey,

I've just made a pull request for some additional units.
In my forked version, I've also added a 'best' function.

So you run:

convert(1200).from('mm').best()

And it will choose the best units (in this case meters) with the logic of highest units where the number is greater than 1.

Do you want a pull request for that?

Units that are industry specific as a plugin or similar

Not everybody wants to convert specific gravity to balling to degrees plato ... but I do. Any thoughts on a plugin mechanism or at least a way to initialize my own units?

Convert not found in angular test

Running unit test for method which uses the convert, fails with message below:
TypeError: undefined is not a constructor (evaluating 'convert_units_1.default(value)')

Repro steps (with angular 6):

1. ng new testapp
2. npm install convert-units

paste below code in app.component.ts

export class AppComponent {
  title = 'app';

  test = convert(12).from('mm').to('cm');

  constructor() {
    console.log(this.test);
  }
}

Running by ng serve will output the result, but running the tests will throw above error.

When importing this module in an angular 5, it won't even work when running ng serve and it throws the same error

Definition: Mass Concentration

Ability to convert between mass concentrations ie ug/l => mg/l

Feature Request: API for injecting custom measures

Currently the only way to add custom measures is to fork the repo and add them there, then open a PR if we want them permanently added to convert-units.

It'd be great to be able to call convert().addMeasure('measureName', measureExports); to add custom measures that don't already exist.

For instance, I would like a "force" measure that converts pound-feet to newton-meters. I'm currently in the process of making a PR for the "force" definition, but it'd be great to have a stop-gap while waiting for that PR to go through.

My project will also implement some custom units that are project specific and those measures wouldn't be relevant to people at-large. Being able to inject those at-will would be excellent.

kilometers missing

according to the docs, kilometers are missing.
Any plans to include them?

Add micrometers (μm) and nanometers (nm)

At my job, we are working with digital camera components like CCD chips. For precise image calculations , we need to store the size of the individual digital pixel sensors on the CCD chip, measured in micrometers. We may also have need for nanometers in the future. I will make a pull request for this issue.

Library specific to Node.js?

After doing some research, it seems that the require() syntax used throughout this library is specific to Node.js.

I don't understand why a library like this can't be written for "bare bones" JavaScript. That would make it useful to the widest range of users. Instead, people like me (who have extensive programming experience, but not much with JavaScript) are kind of left out of the party.

Just sayin'

Temperature fahrenheit Celsius Kelvin

Would temperature conversion code be welcome?

Dependency free

Have you considered making this library dependency free? For bundling it into front-end apps it would be nice for it to not have dependencies on external libraries.

P.S., great library, thanks for all the wonderful work

toBest() doesn't exclude correctly

convert("10.71").from("gal").toBest({exclude: ['ft3']});
#=> {val: 1.4317194879196582, unit: "ft3", singular: "Cubic foot", plural: "Cubic feet"}

I would expect that the exclude option should result in some other unit being selected for a "best" fit.

tag version 2.0?

What changes were introduced in version 2.0.0 published in npm?

Hectoliters PR?

Hectoliters or hl is used in industry and it's simply 100L. Would it be alright if I submitted a pull request to add hl.

I also really would like to add barrels but oil barrels and beer barrels are different sizes.

Proposal - Precision Parameter

Cool library - would be cool if we could specify precision since some applications that would use this may be looking for exact precision.

Thoughts 🤔 ?

Document new features

At least temperature conversion should be added to readme 14a4d53

probably other things as well

convert from metric to imperial

Hello, I have inputs only in metrics, I am trying to convert it to corresponding imperial unit in Angular 2 app.

For example, I am looking for

convert(1000).from('kg').toBest().imperial()

Bytes to KiloByte wrong conversion

Example:
console.log(convert(1024).from('B').toBest())

It will output this { val: 1, unit: 'KB', singular: 'Kilobyte', plural: 'Kilobytes' }

According to goolge unit conversion

Its using 1024 instead of 1000 for kilo byte and returning KB as a unit. Is there any option to change it to 1000.

package licence

hi @jiminikiz ,
Just want to verify,
Is this package is under MIT licence?

Client side usage

As noted here #53

I want to use it in the browser but no success. How to do it?

I did this:

browserify node_modules/convert-units/lib/index.js -o assets/convert-units-dist.js

Now I have convert-units-dist.js in assets folder. I included the script in the page and what's next?
I tried the following with no success:

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

Looks like the browserify does nothing than just bundling all the scripts together but...

Any help is appreciated.

Digital conversions are off

The package's conversions [left] differ from the operating system's calculations [right]

Error in temperature conversions

I was trying to add the temperature unit Rankine but the tests kept failing.
After looking further into it I decided to add a test for F to K which are 2 existing units.

tests['F to K'] = function () {
  assert.strictEqual( convert(32).from('F').to('K'), 273.15);
};

This test should pass but fails with

AssertionError: 151.75 === 273.15

I'm not sure how it's coming up with that as the math seems correct but I can not add Rankine unless the F to K calculation works.

length.js imperial unit in

Cool library! I'm trying to do some conversions in IE8 and it's barfing on the 'in' key (due to being a keyword) in lib/definitions/length.js. Would you be able to stringify that key so it works?

Thanks!

Allow full names of units

Support for more than two systems

The code "works" but the ratios are off because of the third system.
Specifically, I was adding a new definition - fuel consumption, with three systems:
imperial (gallon), us (us gallon) and metric (litre).
[ 'km/l', 'l/100km', 'mi/gal-us', 'gal-us/100mi', 'mi/gal-imp', 'gal-imp/100mi']

Each system has a different ratio when compared to another, so it can't be a fixed number.

Any thoughts?

Nautical Miles are in the github length.js file, but not in the npm published version

1 nautical mile = 1.1508 statute miles

Types are missing from published module on NPM

Hi,

this https://github.com/ben-ng/convert-units/blob/master/lib/index.d.ts

is missing from the published module on NPM

Definition for Third Unit Set

Very cool library. I am trying to use this to build a traditional conversion app.

Length for example, I like to add third unit set, let's call it "Burmese" length. So, there will be 3 sets of unit definitions for length: Metric, Imperial and Burmese. I would like to be able to convert between Metric <=> Imperial, Metric <=> Burmese and Imperial <=> Burmese.

Is there any way to achieve that?

All the singular and plural values in description are first case except tonne

I noticed the first letter of all the singular and plural values in description for mass units are capital except for convert().describe('t') which returns them in lowercase:

{
abbr:"t",
measure:"mass",
system:"metric",
singular:"tonne",
plural:"tonnes"
} 

Any reasons for that?

Missing units

Hello, List of units is not updated, kilometers are missing in the list but convertion with kilometer works.
Also decimeters or decimeters squared miss
Thank you!

Fix naming of imperial tablespoon unit

In the readme the tablespoon unit is called tbsp but in the actual library it is called Tbs. The readme should reflect the correct naming.

Area cm2: sigular and plural name should add square prefix

In area unit, cm2's name should be change.

name: {
singular: 'Square Centimeter',
plural: 'Square Centimeters'
}

Unable to use toBest correctly

Hello

Thanks for the great library!

I am trying to convert from Metric to imperial (ha to ac)

For some reason when I get all the metric options to exclude

const excluded = return convert().list('area').filter((unit) => {
  return unit.system === 'metric';
}).map(item => (item.abbr));

And then try find the toBest() value

convert(100).from('ha').toBest({ exclude: ['m2', 'km2', 'ha', 'cm2', 'mm2'] })

It keeps returning undefined but then as soon as I take one of the excluded options out (such as mm2) it returns a toBest of mm2 and never does it include any of the imperial units?

Sorry if I am making a silly mistake

ClientSide usage

Hi,
First of all, thank you for your effort.
I would like to ask how I can use this js in frontend rather than backend?

Document how to add units

Please document how custom units could be added without hacking those included with the module.

Add support for lookup of unit name from its abbreviation, singular, or plural.

Usage:

convert().lookup('Cups')
/*
  {
    abbr: 'cup'
  , measure: 'volume'
  , system: 'imperial'
  , singular: 'Cup'
  , plural: 'Cups'
  }
*/
convert().lookup('Kilograms', 'mass')
/*
  {
    abbr: 'kg'
  , measure: 'mass'
  , system: 'metric'
  , singular: 'Kilogram'
  , plural: 'Kilograms'
  }
*/

measure is undefined when listing all

When using convert().list() to list all the units, the measure property is always undefined.