Humanize Duration
I have the time in milliseconds and I want it to become "30 minutes" or "3 days, 1 hour". Enter Humanize Duration!
This library is actively maintained but no new features will be added.
Installation
This package is available as humanize-duration on npm and Bower. You can also include the JavaScript file in the browser.
npm install humanize-durationBasic usage
With require (like in Node or with common build systems):
const humanizeDuration = require("humanize-duration");
humanizeDuration(12000); // '12 seconds'With a <script> tag:
<script src="humanize-duration.js"></script>
<script>
humanizeDuration(12000);
</script>Usage
By default, Humanize Duration will humanize down to the second, and will return a decimal for the smallest unit. It will humanize in English by default.
humanizeDuration(3000); // '3 seconds'
humanizeDuration(2250); // '2.25 seconds'
humanizeDuration(97320000); // '1 day, 3 hours, 2 minutes'Options
You can change the settings by passing options as the second argument:
language
Language for unit display (accepts an ISO 639-1 code from one of the supported languages).
humanizeDuration(3000, { language: "es" }); // '3 segundos'
humanizeDuration(5000, { language: "ko" }); // '5 ì´ˆ'fallbacks
Fallback languages if the provided language cannot be found (accepts an ISO 639-1 code from one of the supported languages). It works from left to right.
humanizeDuration(3000, { language: "bad language", fallbacks: ["en"] }); // '3 seconds'
humanizeDuration(3000, {
language: "bad language",
fallbacks: ["bad language", "es"],
}); // '3 segundos'delimiter
String to display between the previous unit and the next value.
humanizeDuration(22140000, { delimiter: " and " }); // '6 hours and 9 minutes'
humanizeDuration(22140000, { delimiter: "--" }); // '6 hours--9 minutes'spacer
String to display between each value and unit.
humanizeDuration(260040000, { spacer: " whole " }); // '3 whole days, 14 whole minutes'
humanizeDuration(260040000, { spacer: "" }); // '3days, 14minutes'largest
Number representing the maximum number of units to display for the duration.
humanizeDuration(1000000000000); // '31 years, 8 months, 1 week, 19 hours, 46 minutes, 40 seconds'
humanizeDuration(1000000000000, { largest: 2 }); // '31 years, 8 months'units
Array of strings to define which units are used to display the duration (if needed). Can be one, or a combination of any, of the following: ['y', 'mo', 'w', 'd', 'h', 'm', 's', 'ms']
humanizeDuration(3600000, { units: ["h"] }); // '1 hour'
humanizeDuration(3600000, { units: ["m"] }); // '60 minutes'
humanizeDuration(3600000, { units: ["d", "h"] }); // '1 hour'round
Boolean value. Use true to round the smallest unit displayed (can be combined with largest and units).
humanizeDuration(1200); // '1.2 seconds'
humanizeDuration(1200, { round: true }); // '1 second'
humanizeDuration(1600, { round: true }); // '2 seconds'decimal
String to substitute for the decimal point in a decimal fraction.
humanizeDuration(1200); // '1.2 seconds'
humanizeDuration(1200, { decimal: " point " }); // '1 point 2 seconds'conjunction
String to include before the final unit. You can also set serialComma to false to eliminate the final comma.
humanizeDuration(22140000, { conjunction: " and " }); // '6 hours and 9 minutes'
humanizeDuration(22141000, { conjunction: " and " }); // '6 hours, 9 minutes, and 1 second'
humanizeDuration(22140000, { conjunction: " and ", serialComma: false }); // '6 hours and 9 minutes'
humanizeDuration(22141000, { conjunction: " and ", serialComma: false }); // '6 hours, 9 minutes and 1 second'maxDecimalPoints
Number that defines a maximal decimal points for float values.
humanizeDuration(8123.456789); // 8.12 seconds
humanizeDuration(8123.456789, { maxDecimalPoints: 3 }); // 8.123 seconds
humanizeDuration(8123.456789, { maxDecimalPoints: 6 }); // 8.123456 seconds
humanizeDuration(8123.45, { maxDecimalPoints: 6 }); // 8.12345 seconds
humanizeDuration(8000, { maxDecimalPoints: 6 }); // 8 secondsunitMeasures
Customize the value used to calculate each unit of time.
humanizeDuration(400); // '0.4 seconds'
humanizeDuration(400, {
unitMeasures: {
y: 365,
mo: 30,
w: 7,
d: 1,
},
}); // '1 year, 1 month, 5 days'Combined example
humanizeDuration(3602000, {
language: "es",
round: true,
spacer: " glorioso ",
units: ["m"],
}); // '60 glorioso minutos'Humanizers
If you find yourself setting same options over and over again, you can create a humanizer that changes the defaults, which you can still override later.
const spanishHumanizer = humanizeDuration.humanizer({
language: "es",
units: ["y", "mo", "d"],
});
spanishHumanizer(71177400000); // '2 años, 3 meses, 2 dÃas'
spanishHumanizer(71177400000, { units: ["d", "h"] }); // '823 dÃas, 19.5 horas'You can also add new languages to humanizers. For example:
const shortEnglishHumanizer = humanizeDuration.humanizer({
language: "shortEn",
languages: {
shortEn: {
y: () => "y",
mo: () => "mo",
w: () => "w",
d: () => "d",
h: () => "h",
m: () => "m",
s: () => "s",
ms: () => "ms",
},
},
});
shortEnglishHumanizer(15600000); // '4 h, 20 m'You can also add languages after initializing:
const humanizer = humanizeDuration.humanizer()
humanizer.languages.shortEn = {
y: () => 'y',
// ...Internally, the main humanizeDuration function is just a wrapper around a humanizer.
Supported languages
Humanize Duration supports the following languages:
| Language | Code |
|---|---|
| Afrikaans | af |
| Albanian | sq |
| Arabic | ar |
| Basque | eu |
| Bengali | bn |
| Bulgarian | bg |
| Catalan | ca |
| 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 |
| Vietnamese | vi |
| Welsh | cy |
For a list of supported languages, you can use the getSupportedLanguages function. The results may not be in the same order every time.
humanizeDuration.getSupportedLanguages();
// ['ar', 'bg', 'ca', 'cs', da', 'de', ...]This function won't return any new languages you define; it will only return the defaults supported by the library.
Credits
Lovingly made by Evan Hahn with help from:
- Martin Prins for language support
- Filipi Siqueira for Portuguese support
- Peter Rekdal Sunde for Norwegian support
- Michał Janiec for Polish support
- Eileen Li for Chinese support
- Tommy Brunn for Swedish support
- Giovanni Pellerano for Italian support
- Rahma Sghaier for Arabic support
- Evgenios Kastanias for Greek support
- Oleksii Mylotskyi for Ukrainian support
- Patrik Simek for Czech support
- Toni Helminen for Finnish support
- Vidmantas Drasutis for Lithuanian support
- Manh Tuan for Vietnamese support
- Leonard Lee for Indonesian & Malay support
- Jesse Jackson for documentation help
- Óli Tómas Freysson for Icelandic support
- Saeed Ganji for Farsi/Persian support
- Caner Elci for Bulgarian support
- Matej Kolesár for Slovak support
- Abdul Jalil for Urdu support
- Wasuwat Limsuparhat for Thai support
- Malikoun for Lao support
- Villu Orav for Estonian support
- Harijs Deksnis for Latvian support
- Nirmala Thapa(Subit) for Faroese support
- Fahad Kassim for Swahili support
- Prayag Roy Choudhury for updating Mocha
- Aryan Rawlani for Hindi support
- Kristijan Jesenski for Slovenian support
- Michal Karzel for improving Arabic support
Licensed under the permissive Unlicense. Enjoy!
Related modules
- pretty-ms
- angularjs-humanize-duration
- millisec
- HumanizeDuration.ts, a TypeScript version of this module
- aurelia-time
- Fork that adds a
timeAdverboption