Options
All
  • Public
  • Public/Protected
  • All
Menu

convert

Convert

The smallest & fastest library for really easy, totally type-safe unit conversions in TypeScript & JavaScript.

Codecov

npm install convert
# or
yarn add convert
convert(5, 'miles').to('km');
convertMany('4d 16h').to('minutes');

Features

  • Full build time and runtime checks of conversions
  • Using a web framework like Next.js or Nuxt.js? You get 0-cost build-time conversions. Convert is totally side-effect free, so conversions will be precalculated at build-time, so absolutely zero conversion code is sent to clients!
  • Works in browsers and Node.js (UMD, ESModules, and CommonJS builds provided)
  • Out of the box ES3 backwards-compatibility (works since Node.js 0.9.1, probably earlier)
  • 0 dependencies
  • Supports bigints if you pass something with typeof bigint

Usage

API documentation for the latest version is generated and available online.

View docs.

// ESM:
import convert from 'convert';
// CJS:
const {convert} = require('convert');

// 360 seconds into minutes
convert(360, 'seconds').to('minutes');
// -> 6

// BigInt support
convert(20n, 'hours').to('minutes');
// -> 1200n

// We also do length, data, volume, mass, temperature, and more
convert(5, 'kilometers').to('nautical miles');
convert(12, 'pounds').to('ounces');
convert(64, 'bytes').to('KiB');
convert(10, 'atmospheres').to('kPa');
convert(451, 'fahrenheit').to('celsius');

Converting many units

import {convertMany} from 'convert';
const {convertMany} = require('convert');

// Convert 1 day and 8 hours into ms
convertMany('1d8h').to('ms');

Alternatives

All of them are bad because they aren't as small and are slower than convert. Benchmarks of popular unit conversion libraries, including convert are available here.

Convert is the fastest, taking less than a microsecond for all functions. That's a little over 3 million convert() calls per second.

npm bundle size of convert

npm bundle size of uom + npm bundle size of uom-units

npm bundle size of units-converter

npm bundle size of safe-units

npm bundle size of convert-units

npm bundle size of js-quantities

Thanks

Big thanks to @Jdender, @TheAkio, @iCrawl, @p7g, @aequasi, @aetheryx, and the TypeScript Discord server for their help in getting the typesafety working.

Thanks to @MicroDroid for fixing temperature conversion.

Generated using TypeDoc