Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/jonahsnider/convert
The smallest & fastest library for really easy, totally type-safe unit conversions in TypeScript & JavaScript.
https://github.com/jonahsnider/convert
conversion conversions convert convert-units hacktoberfest javascript metric nodejs si-units typescript unit-conversions uom
Last synced: 5 days ago
JSON representation
The smallest & fastest library for really easy, totally type-safe unit conversions in TypeScript & JavaScript.
- Host: GitHub
- URL: https://github.com/jonahsnider/convert
- Owner: jonahsnider
- License: mit
- Created: 2020-05-17T09:01:49.000Z (over 4 years ago)
- Default Branch: main
- Last Pushed: 2024-10-29T09:18:05.000Z (20 days ago)
- Last Synced: 2024-10-29T10:49:44.538Z (20 days ago)
- Topics: conversion, conversions, convert, convert-units, hacktoberfest, javascript, metric, nodejs, si-units, typescript, unit-conversions, uom
- Language: TypeScript
- Homepage: https://convert.js.org
- Size: 25.2 MB
- Stars: 124
- Watchers: 3
- Forks: 18
- Open Issues: 6
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# Convert
The [smallest](https://bundlephobia.com/package/convert) & [fastest](https://github.com/jonahsnider/js-unit-conversion-benchmarks) library for really easy, totally type-safe unit conversions in TypeScript & JavaScript.
[](https://bundlephobia.com/package/convert)
[](https://www.npmjs.com/package/convert)
```sh
npm install convert
# or
yarn add convert
```
[**More installation examples below**](#Installation).
```js
convert(5, "miles").to("km");
convertMany("4d 16h").to("minutes");
```
## Features
- Full build time and runtime validation of conversions
- Web frameworks like Next.js and Vite know that Convert is side-effect free, so [conversions will be precalculated at build-time](https://github.com/jonahsnider/convert/blob/main/docs/build-time-optimizations.tsx), absolutely zero conversion code is sent to clients
- Runs anywhere (browsers, Node, Bun, etc), full ES3 backwards-compatibility
- Tiny bundle size and 0 dependencies
- Supports bigints
## Usage
Generated API documentation for the latest version is available online.
[**View docs**](https://convert.js.org).
```ts
// 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.5 km' }
// You can 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
```ts
import { convertMany } from "convert";
const { convertMany } = require("convert");
// Convert 1 day and 8 hours into ms
convertMany("1d8h").to("ms");
```
### Converting to best unit
```ts
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.5 d' }
// 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.5 km' }
convert(3.5, "km").to("best", "metric"); // -> { quantity: 3.5, unit: 'km', toString: () => '3.5 km' }
convert(3.5, "km").to("best", "imperial"); // -> { quantity: 2.17, unit: 'mi', toString: () => '3.5 mi' }
```
### `ms` shorthand
```ts
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.
```sh
npm install convert
# or
yarn add convert
```
And then import it in your code like this:
```js
// CommonJS
const { convert } = require("convert");
// ESM
import convert from "convert";
```
### Browsers
Pick your favorite CDN:
#### ES Modules via CDN
```html
import convert from "https://cdn.skypack.dev/convert@5";
import convert from "https://esm.run/convert@5";
import convert from "https://cdn.jsdelivr.net/npm/convert@5";
import convert from "https://unpkg.com/convert@5";
```
#### UMD (global)
```html
```
## 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](https://github.com/jonahsnider/js-unit-conversion-benchmarks).
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
[](https://bundlephobia.com/result?p=convert)
[](https://bundlephobia.com/result?p=safe-units)
[](https://bundlephobia.com/result?p=convert-units)
[](https://bundlephobia.com/result?p=js-quantities)
[](https://bundlephobia.com/result?p=uom)
[](https://bundlephobia.com/result?p=uom-units)