---

---

Install

1npm install @visulima/humanizer

1yarn add @visulima/humanizer

1pnpm add @visulima/humanizer

Usage

Bytes

Convert bytes to human-readable strings and vice versa: 1024 → 1KB and 1KB → 1024

1import { formatBytes, parseBytes } from "@visulima/humanizer";
2
3console.log(formatBytes(123412341, { decimals: 2 })); // "117.70 MB"
4console.log(parseBytes("117.70 MB")); // 123417395.2
5
6// Localization support in both directions
7console.log(formatBytes(123412341, { decimals: 2, locale: "de" })); // "117,70 MB"
8console.log(parseBytes("117,70 MB", { locale: "de" })); // 123417395.2
9
10// Use a specified unit
11console.log(formatBytes(123412341, { decimals: 2, unit: "KB" })); // "120,519.86 KB"
12
13// Use a long unit
14console.log(formatBytes(123412341, { decimals: 2, unit: "GB", long: true })); // "0.11 Gigabytes"
15
16// Use a differnet base
17console.log(formatBytes(123412341, { decimals: 2, base: 10 })); // "123.41 MB"

Supported locales

Default: "en".

formatBytes and parseBytes supports the following locales:

Supported locales

• af-NA"
• af"
• agq"
• ak"
• am"
• ar-AE"
• ar-BH"
• ar-DJ"
• ar-DZ"
• ar-EG"
• ar-EH"
• ar-ER"
• ar-IL"
• ar-IQ"
• ar-JO"
• ar-KM"
• ar-KW"
• ar-LB"
• ar-LY"
• ar-MA"
• ar-MR"
• ar-OM"
• ar-PS"
• ar-QA"
• ar-SA"
• ar-SD"
• ar-SO"
• ar-SS"
• ar-SY"
• ar-TD"
• ar-TN"
• ar-YE"
• ar"
• as"
• asa"
• ast"
• az-Cyrl"
• az-Latn"
• az"
• bas"
• be-tarask"
• be"
• bem"
• bez"
• bg"
• bm"
• bn-IN"
• bn"
• bo-IN"
• bo"
• br"
• brx"
• bs-Cyrl"
• bs-Latn"
• bs"
• ca-AD"
• ca-ES-valencia"
• ca-FR"
• ca-IT"
• ca"
• ccp-IN"
• ccp"
• ce"
• ceb"
• cgg"
• chr"
• ckb-IR"
• ckb"
• cs"
• cy"
• da-GL"
• da"
• dav"
• de-AT"
• de-BE"
• de-CH"
• de-IT"
• de-LI"
• de-LU"
• de"
• dje"
• doi"
• dsb"
• dua"
• dyo"
• dz"
• ebu"
• ee-TG"
• ee"
• el-CY"
• el"
• en-001"
• en-150"
• en-AE"
• en-AG"
• en-AI"
• en-AS"
• en-AT"
• en-AU"
• en-BB"
• en-BE"
• en-BI"
• en-BM"
• en-BS"
• en-BW"
• en-BZ"
• en-CA"
• en-CC"
• en-CH"
• en-CK"
• en-CM"
• en-CX"
• en-CY"
• en-DE"
• en-DG"
• en-DK"
• en-DM"
• en-ER"
• en-FI"
• en-FJ"
• en-FK"
• en-FM"
• en-GB"
• en-GD"
• en-GG"
• en-GH"
• en-GI"
• en-GM"
• en-GU"
• en-GY"
• en-HK"
• en-IE"
• en-IL"
• en-IM"
• en-IN"
• en-IO"
• en-JE"
• en-JM"
• en-KE"
• en-KI"
• en-KN"
• en-KY"
• en-LC"
• en-LR"
• en-LS"
• en-MG"
• en-MH"
• en-MO"
• en-MP"
• en-MS"
• en-MT"
• en-MU"
• en-MW"
• en-MY"
• en-NA"
• en-NF"
• en-NG"
• en-NL"
• en-NR"
• en-NU"
• en-NZ"
• en-PG"
• en-PH"
• en-PK"
• en-PN"
• en-PR"
• en-PW"
• en-RW"
• en-SB"
• en-SC"
• en-SD"
• en-SE"
• en-SG"
• en-SH"
• en-SI"
• en-SL"
• en-SS"
• en-SX"
• en-SZ"
• en-TC"
• en-TK"
• en-TO"
• en-TT"
• en-TV"
• en-TZ"
• en-UG"
• en-UM"
• en-VC"
• en-VG"
• en-VI"
• en-VU"
• en-WS"
• en-ZA"
• en-ZM"
• en-ZW"
• en"
• eo"
• es-419"
• es-AR"
• es-BO"
• es-BR"
• es-BZ"
• es-CL"
• es-CO"
• es-CR"
• es-CU"
• es-DO"
• es-EA"
• es-EC"
• es-GQ"
• es-GT"
• es-HN"
• es-IC"
• es-MX"
• es-NI"
• es-PA"
• es-PE"
• es-PH"
• es-PR"
• es-PY"
• es-SV"
• es-US"
• es-UY"
• es-VE"
• es"
• et"
• eu"
• ewo"
• fa-AF"
• fa"
• ff-Adlm-BF"
• ff-Adlm-CM"
• ff-Adlm-GH"
• ff-Adlm-GM"
• ff-Adlm-GW"
• ff-Adlm-LR"
• ff-Adlm-MR"
• ff-Adlm-NE"
• ff-Adlm-NG"
• ff-Adlm-SL"
• ff-Adlm-SN"
• ff-Adlm"
• ff-Latn-BF"
• ff-Latn-CM"
• ff-Latn-GH"
• ff-Latn-GM"
• ff-Latn-GN"
• ff-Latn-GW"
• ff-Latn-LR"
• ff-Latn-MR"
• ff-Latn-NE"
• ff-Latn-NG"
• ff-Latn-SL"
• ff-Latn"
• ff"
• fi"
• fil"
• fo-DK"
• fo"
• fr-BE"
• fr-BF"
• fr-BI"
• fr-BJ"
• fr-BL"
• fr-CA"
• fr-CD"
• fr-CF"
• fr-CG"
• fr-CH"
• fr-CI"
• fr-CM"
• fr-DJ"
• fr-DZ"
• fr-GA"
• fr-GF"
• fr-GN"
• fr-GP"
• fr-GQ"
• fr-HT"
• fr-KM"
• fr-LU"
• fr-MA"
• fr-MC"
• fr-MF"
• fr-MG"
• fr-ML"
• fr-MQ"
• fr-MR"
• fr-MU"
• fr-NC"
• fr-NE"
• fr-PF"
• fr-PM"
• fr-RE"
• fr-RW"
• fr-SC"
• fr-SN"
• fr-SY"
• fr-TD"
• fr-TG"
• fr-TN"
• fr-VU"
• fr-WF"
• fr-YT"
• fr"
• fur"
• fy"
• ga-GB"
• ga"
• gd"
• gl"
• gsw-FR"
• gsw-LI"
• gsw"
• gu"
• guz"
• gv"
• ha-GH"
• ha-NE"
• ha"
• haw"
• he"
• hi"
• hr-BA"
• hr"
• hsb"
• hu"
• hy"
• ia"
• id"
• ig"
• ii"
• is"
• it-CH"
• it-SM"
• it-VA"
• it"
• ja"
• jgo"
• jmc"
• jv"
• ka"
• kab"
• kam"
• kde"
• kea"
• kgp"
• khq"
• ki"
• kk"
• kkj"
• kl"
• kln"
• km"
• kn"
• ko-KP"
• ko"
• kok"
• ks-Arab"
• ks"
• ksb"
• ksf"
• ksh"
• ku"
• kw"
• ky"
• lag"
• lb"
• lg"
• lkt"
• ln-AO"
• ln-CF"
• ln-CG"
• ln"
• lo"
• lrc-IQ"
• lrc"
• lt"
• lu"
• luo"
• luy"
• lv"
• mai"
• mas-TZ"
• mas"
• mer"
• mfe"
• mg"
• mgh"
• mgo"
• mi"
• mk"
• ml"
• mn"
• mni-Beng"
• mni"
• mr"
• ms-BN"
• ms-ID"
• ms-SG"
• ms"
• mt"
• mua"
• my"
• mzn"
• naq"
• nb-SJ"
• nb"
• nd"
• nds-NL"
• nds"
• ne-IN"
• ne"
• nl-AW"
• nl-BE"
• nl-BQ"
• nl-CW"
• nl-SR"
• nl-SX"
• nl"
• nmg"
• nn"
• nnh"
• no"
• nus"
• nyn"
• om-KE"
• om"
• or"
• os-RU"
• os"
• pa-Arab"
• pa-Guru"
• pa"
• pcm"
• pl"
• ps-PK"
• ps"
• pt-AO"
• pt-CH"
• pt-CV"
• pt-GQ"
• pt-GW"
• pt-LU"
• pt-MO"
• pt-MZ"
• pt-PT"
• pt-ST"
• pt-TL"
• pt"
• qu-BO"
• qu-EC"
• qu"
• rm"
• rn"
• ro-MD"
• ro"
• rof"
• ru-BY"
• ru-KG"
• ru-KZ"
• ru-MD"
• ru-UA"
• ru"
• rw"
• rwk"
• sa"
• sah"
• saq"
• sat-Olck"
• sat"
• sbp"
• sc"
• sd-Arab"
• sd-Deva"
• sd"
• se-FI"
• se-SE"
• se"
• seh"
• ses"
• sg"
• shi-Latn"
• shi-Tfng"
• shi"
• si"
• sk"
• sl"
• smn"
• sn"
• so-DJ"
• so-ET"
• so-KE"
• so"
• sq-MK"
• sq-XK"
• sq"
• sr-Cyrl-BA"
• sr-Cyrl-ME"
• sr-Cyrl-XK"
• sr-Cyrl"
• sr-Latn-BA"
• sr-Latn-ME"
• sr-Latn-XK"
• sr-Latn"
• sr"
• su-Latn"
• su"
• sv-AX"
• sv-FI"
• sv"
• sw-CD"
• sw-KE"
• sw-UG"
• sw"
• ta-LK"
• ta-MY"
• ta-SG"
• ta"
• te"
• teo-KE"
• teo"
• tg"
• th"
• ti-ER"
• ti"
• tk"
• to"
• tr-CY"
• tr"
• tt"
• twq"
• tzm"
• ug"
• uk"
• und"
• ur-IN"
• ur"
• uz-Arab"
• uz-Cyrl"
• uz-Latn"
• uz"
• vai-Latn"
• vai-Vaii"
• vai"
• vi"
• vun"
• wae"
• wo"
• xh"
• xog"
• yav"
• yi"
• yo-BJ"
• yo"
• yrl-CO"
• yrl-VE"
• yrl"
• yue-Hans"
• yue-Hant"
• yue"
• zgh"
• zh-Hans-HK"
• zh-Hans-MO"
• zh-Hans-SG"
• zh-Hans"
• zh-Hant-HK"
• zh-Hant-MO"
• zh-Hant"
• zh"
• zu"

Duration

duration and parseDuration functionality is based on a modified version of HumanizeDuration.

Format time in milliseconds into a human-readable string like "30 minutes" or "3 days, 1 hour". Parse various human-readable duration strings back into milliseconds.

1import { duration, parseDuration } from "@visulima/humanizer";
2import { durationLanguage as fr } from "@visulima/humanizer/language/fr"; // Example language import
3
4// --- Formatting ---
5console.log(duration(3000));
6// => "3 seconds"
7
8console.log(duration(2250));
9// => "2.25 seconds"
10
11console.log(duration(97320000));
12// => "1 day, 3 hours, 2 minutes"
13
14// --- Parsing ---
15console.log(parseDuration("1 day, 3 hours, 2 minutes"));
16// => 97320000
17
18console.log(parseDuration("2h 30 min"));
19// => 9000000
20
21console.log(parseDuration("-3 weeks"));
22// => -1814400000
23
24console.log(parseDuration("1.5 years"));
25// => 47335428000
26
27// Parsing with different languages (requires language object with unitMap)
28console.log(parseDuration("2 jours et 5 heures", { language: fr }));
29// => 190800000
30
31// Parsing colon format (H:MM:SS or MM:SS)
32console.log(parseDuration("1:25:05"));
33// => 5105000
34
35console.log(parseDuration("15:30"));
36// => 930000
37
38// Parsing ISO 8601 duration format (PT#H#M#S)
39console.log(parseDuration("PT2H30M5S"));
40// => 9005000
41
42// Parsing just numbers (uses defaultUnit)
43console.log(parseDuration("1500")); // Default unit is 'ms'
44// => 1500

Options for duration

You can change the formatting settings by passing options as the second argument to duration.

units

Array of possible units to use. Units are y, mo, w, d, h, m, s, and ms.

Units are skipped if their count is zero. For example, if you pass a duration of 1000 and units ["h", "m", "s"], the output will be "1 second".

Must be in descending order of unit size. For example, ["h", "m"] is valid but ["m", "h"] is not.

Default: ["y", "mo", "w", "d", "h", "m", "s"]

1duration(69000, { units: ["h", "m", "s", "ms"] });
2// => "1 minute, 9 seconds"
3
4duration(3600000, { units: ["h"] });
5// => "1 hour"
6
7duration(3600000, { units: ["m"] });
8// => "60 minutes"
9
10duration(3600000, { units: ["d", "h"] });
11// => "1 hour"

largest

Integer representing the maximum number of units to use.

Default: Infinity

1duration(1000000000000);
2// => "31 years, 8 months, 1 week, 19 hours, 46 minutes, 40 seconds"
3
4duration(1000000000000, { largest: 2 });
5// => "31 years, 8 months"

round

A boolean that, if true, rounds the smallest unit.

Default: false

1duration(1200);
2// => "1.2 seconds"
3
4duration(1200, { round: true });
5// => "1 second"
6
7duration(1600, { round: true });
8// => "2 seconds"

delimiter

String to display between units.

Default: ", " in most languages, " ﻭ " for Arabic

1duration(22140000);
2// => "6 hours, 9 minutes"
3
4duration(22140000, { delimiter: " and " });
5// => "6 hours and 9 minutes"

spacer

String to display between the count and the word.

Default: " "

1duration(260040000);
2// => "3 days, 14 minutes"
3
4duration(260040000, { spacer: " whole " });
5// => "3 whole days, 14 whole minutes"

decimal

String to display between the integer and decimal parts of a count, if relevant.

Default depends on the language.

1duration(1200);
2// => "1.2 seconds"
3
4duration(1200, { decimal: " point " });
5// => "1 point 2 seconds"

conjunction

String to include before the final unit.

You can also set serialComma to false to eliminate the final comma.

Default: ""

1duration(22140000, { conjunction: " and " });
2// => "6 hours and 9 minutes"
3
4duration(22141000, { conjunction: " and " });
5// => "6 hours, 9 minutes, and 1 second"
6
7duration(22140000, { conjunction: " and ", serialComma: false });
8// => "6 hours and 9 minutes"
9
10duration(22141000, { conjunction: " and ", serialComma: false });
11// => "6 hours, 9 minutes and 1 second"

maxDecimalPoints

Integer that defines the maximum number of decimal points to show, if relevant. If undefined, the count will be converted to a string using Number.prototype.toString().

This does not round any numbers. See the round option.

Default: undefined

1duration(8123.456789);
2// => "8.123456789 seconds"
3
4duration(8123.456789, { maxDecimalPoints: 3 });
5// => "8.123 seconds"
6
7duration(8100, { maxDecimalPoints: 99 });
8// => "8.1 seconds"
9
10duration(8000, { maxDecimalPoints: 99 });
11// => "8 seconds"
12
13duration(7999, { maxDecimalPoints: 2 });
14// => "7.99 seconds"

digitReplacements

Array of ten strings to which will replace the numerals 0-9. Useful if a language uses different numerals.

Default: undefined for most languages, ["۰", "١", "٢", "٣", "٤", "٥", "٦", "٧", "٨", "٩"] for Arabic

1duration(1234);
2// => "1.234 seconds"
3
4duration(1234, {
5    digitReplacements: ["Zero", "One", "Two", "Three", "Four", "Five", "Six", "Seven", "Eight", "Nine"],
6});
7// => "One.TwoThreeFour seconds"

unitMeasures

Use this option with care. It is an advanced feature.

Object used to customize the value used to calculate each unit of time. Most useful when you want to update the length of years or months, which have ambiguous lengths.

Default: { y: 31557600000, mo: 2629800000, w: 604800000, d: 86400000, h: 3600000, m: 60000, s: 1000, ms: 1 }

1duration(2629800000);
2// => "1 month"
3
4duration(2629800000, {
5    unitMeasures: {
6        y: 31557600000,
7        mo: 30 * 86400000,
8        w: 604800000,
9        d: 86400000,
10        h: 3600000,
11        m: 60000,
12        s: 1000,
13        ms: 1,
14    },
15});
16// => "1 month, 10 hours, 30 minutes"

language

Language for unit display. Accepts an ISO 639-1 code from one of the supported languages, or a custom language object.

Default: en (English language object).

1import { duration } from "@visulima/humanizer";
2import { durationLanguage as es } from "@visulima/humanizer/language/es";
3import { durationLanguage as ko } from "@visulima/humanizer/language/ko";
4
5duration(3000, { language: es });
6// => "3 segundos"
7
8duration(5000, { language: ko });
9// => "5 초"

Options for parseDuration

You can pass options as the second argument to parseDuration.

language

Language object containing the unitMap for parsing localized strings. See the language option for the duration function for details on how to import language objects.

If omitted or if the language object doesn't have a unitMap, parsing will only recognize standard English units (like "hour", "min", "d", "ms" etc.).

Default: English units.

1import { parseDuration } from "@visulima/humanizer";
2import { durationLanguage as de } from "@visulima/humanizer/language/de";
3import { durationLanguage as ru } from "@visulima/humanizer/language/ru";
4
5// Without language option (or if unitMap is missing)
6parseDuration("3 Stunden"); // => undefined
7parseDuration("5 часов"); // => undefined
8
9// With language option containing a unitMap
10parseDuration("3 Stunden", { language: de });
11// => 10800000
12
13parseDuration("5 часов, 10 минут", { language: ru });
14// => 18600000

defaultUnit

Specifies the unit to assume if the input string is just a number (without any units).

Possible values: y, mo, w, d, h, m, s, ms.

Default: "ms"

1parseDuration("1500");
2// => 1500 (interpreted as 1500 ms)
3
4parseDuration("1500", { defaultUnit: "s" });
5// => 1500000 (interpreted as 1500 s)
6
7parseDuration("-10", { defaultUnit: "d" });
8// => -864000000 (interpreted as -10 days)

Supported languages

duration and parseDuration (when provided with a language object containing a unitMap) support the following languages:

Language	Code
Afrikaans	af
Albanian	sq
Amharic	am
Arabic	ar
Basque	eu
Bengali	bn
Bulgarian	bg
Catalan	ca
Central Kurdish	ckb
Chinese, simplified	zh_CN
Chinese, traditional	zh_TW
Croatian	hr
Czech	cs
Danish	da
Dutch	nl
English	en
Esperanto	eo
Estonian	et
Faroese	fo
Farsi/Persian	fa
Finnish	fi
French	fr
German	de
Greek	el
Hebrew	he
Hindi	hi
Hungarian	hu
Icelandic	is
Indonesian	id
Italian	it
Japanese	ja
Kannada	kn
Khmer	km
Korean	ko
Kurdish	ku
Lao	lo
Latvian	lv
Lithuanian	lt
Macedonian	mk
Mongolian	mn
Malay	ms
Marathi	mr
Norwegian	no
Polish	pl
Portuguese	pt
Romanian	ro
Russian	ru
Serbian	sr
Slovak	sk
Slovenian	sl
Spanish	es
Swahili	sw
Swedish	sv
Tamil	ta
Telugu	te
Thai	th
Turkish	tr
Ukrainian	uk
Urdu	ur
Uzbek	uz
Uzbek (Cyrillic)	uz_CYR
Vietnamese	vi
Welsh	cy

Related

Bytes

• pretty-bytes - Convert bytes to a human readable string: 1337 → 1.34 kB

Duration

• HumanizeDuration - 361000 becomes "6 minutes, 1 second"
• pretty-ms - Convert milliseconds to a human readable string: 1337000000 → 15d 11h 23m 20s

Supported Node.js Versions

Libraries in this ecosystem make the best effort to track Node.js' release schedule. Here's a post on why we think this is important.

Contributing

If you would like to help take a look at the list of issues and check our Contributing guidelines.

Note: please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.

Credits

• Daniel Bannert
• All Contributors

License

The visulima humanizer is open-sourced software licensed under the [MIT][license-url]

[typescript-url]: https://www.typescriptlang.org/ "TypeScript" "typescript" [license-image]: https://img.shields.io/npm/l/@visulima/humanizer?color=blueviolet&style=for-the-badge [license-url]: LICENSE.md "license" [npm-image]: https://img.shields.io/npm/v/@visulima/humanizer/latest.svg?style=for-the-badge&logo=npm [npm-url]: https://www.npmjs.com/package/@visulima/humanizer/v/latest "npm"