Code Monkey home page Code Monkey logo

convert's Introduction

Convert

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

bundle size npm monthly downloads

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 via npm Registry

// 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:

ES Modules via CDN

<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

convert's People

Contributors

renovate[bot] avatar jonahsnider avatar renovate-bot avatar dependabot[bot] avatar filipef101 avatar furrycatherder avatar cyruseuros avatar

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.