Nutrient Packed Morsels

    convert
    TypeScript icon, indicating that this package has built-in type declarations

    4.5.0 • Public • Published

    Convert

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

    published npm version test coverage bundle size npm monthly downloads type definitions license CI

    npm install convert
    # or
    yarn add convert

    More installation examples below, including browser builds.

    convert(5, 'miles').to('km');
    convertMany('4d 16h').to('minutes');

    Features

    • Full build time and runtime validation 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 and ESM builds will work anywhere)
    • Out of the box ES3 backwards-compatibility (CI tests on Node.js v0.9.1)
    • Absolutely tiny bundle size and 0 dependencies
    • Supports bigints without breaking on old engines

    Usage

    Generated API documentation for the latest version is 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
    
    // Format to the best unit automatically
    convert(5500, 'meters').to('best');
    // -> { quantity: 5.5, unit: 'km', toString: () => '5.5km' }
    
    // We also do length, data, volume, mass, temperature, and more
    convert(5, 'kilometers').to('nautical miles');
    convert(12, 'pounds').to('ounces');
    convert(8192, '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');

    Converting to best unit

    import convert from 'convert';
    const {convert} = require('convert');
    
    // Convert into the best unit
    const duration = convert(36, 'h').to('best');
    // -> { quantity: 1.5, unit: 'd', toString: () => '1.5d' }
    
    // The toString() method means you can automatically cast the object to a string without any issues
    'duration is ' + duration;
    // -> duration is 1.5d
    
    // You can also specify to use a specific kind of units (metric or imperial, metric is default)
    convert(3.5, 'km').to('best'); // -> { quantity: 3.5, unit: 'km', toString: () => '3.5km' }
    convert(3.5, 'km').to('best', 'metric'); // -> { quantity: 3.5, unit: 'km', toString: () => '3.5km' }
    convert(3.5, 'km').to('best', 'imperial'); // -> { quantity: 2.17, unit: 'mi', toString: () => '3.5mi' }

    ms shorthand

    import {ms} from 'convert';
    const {ms} = require('convert');
    
    // Convert a duration into milliseconds
    ms('1d 2h 30min');
    // -> 95400000
    
    // Convert milliseconds to a string
    ms(86400000);
    // -> '1d'

    Installation

    Package manager

    Convert is published as convert on npm.

    npm install convert
    # or
    yarn add convert

    CommonJS

    // This chooses which build to use depending on NODE_ENV
    const {convert} = require('convert');
    
    // You can also specify which build to use
    const {convert} = require('convert/dev');
    const {convert} = require('convert/prod');

    ES Modules

    // The production build is the default
    import convert from 'convert';
    
    // ESM does not have automatic build switching, you must explicitly import the dev build
    import convert from 'convert/dev';
    import convert from 'convert/prod';

    Browsers

    Pick your favorite CDN:

    Modules

    <script type="module">
    	import convert from 'https://cdn.skypack.dev/convert@4';
    	import convert from 'https://esm.run/convert@4';
    	import convert from 'https://cdn.jsdelivr.net/npm/convert@4';
    	import convert from 'https://unpkg.com/convert@4';
    </script>

    UMD (global)

    <script src="https://cdn.jsdelivr.net/npm/convert@4/dist/convert.prod.js"></script>
    <script src="https://unpkg.com/convert@4/dist/convert.prod.js"></script>

    Alternatives

    Convert is better than other unit conversion libraries because it's faster and smaller than them, while having the same features. 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.

    Bundle size comparison

    npm bundle size of convert

    npm bundle size of safe-units

    npm bundle size of convert-units

    npm bundle size of js-quantities

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

    Install

    npm i convert

    DownloadsWeekly Downloads

    3,158

    Version

    4.5.0

    License

    MIT

    Unpacked Size

    932 kB

    Total Files

    14

    Last publish

    Collaborators

    • jonahsnider