humanize-duration

What is humanize-duration?

The humanize-duration npm package is used to convert durations, given in milliseconds, into human-readable strings. It is useful for displaying time durations in a more understandable format for users.

What are humanize-duration's main functionalities?

Basic Usage

This feature allows you to convert a duration in milliseconds to a human-readable string. In this example, 3000 milliseconds is converted to '3 seconds'.

const humanizeDuration = require('humanize-duration');
console.log(humanizeDuration(3000)); // '3 seconds'

Custom Units

This feature allows you to specify custom units for the duration. In this example, 3600000 milliseconds is converted to '1 hour' using hours and minutes as units.

const humanizeDuration = require('humanize-duration');
console.log(humanizeDuration(3600000, { units: ['h', 'm'] })); // '1 hour'

Language Support

This feature allows you to specify the language for the output string. In this example, 3000 milliseconds is converted to '3 segundos' in Spanish.

const humanizeDuration = require('humanize-duration');
console.log(humanizeDuration(3000, { language: 'es' })); // '3 segundos'

Round

This feature allows you to round the duration to the nearest unit. In this example, 1234567 milliseconds is rounded to '20 minutes'.

const humanizeDuration = require('humanize-duration');
console.log(humanizeDuration(1234567, { round: true })); // '20 minutes'

Largest

This feature allows you to limit the number of units in the output string. In this example, 1234567890 milliseconds is converted to '14 days, 6 hours' with a limit of 2 units.

const humanizeDuration = require('humanize-duration');
console.log(humanizeDuration(1234567890, { largest: 2 })); // '14 days, 6 hours'

Other packages similar to humanize-duration

moment

Moment.js is a comprehensive library for parsing, validating, manipulating, and formatting dates and times in JavaScript. It includes functionality for humanizing durations, but it is more heavyweight compared to humanize-duration.

date-fns

date-fns is a modern JavaScript date utility library that provides a variety of functions for working with dates, including humanizing durations. It is modular and tree-shakeable, making it a lighter alternative to Moment.js.

luxon

Luxon is a modern JavaScript library for working with dates and times, created by one of the Moment.js developers. It offers a more modern API and includes features for humanizing durations, similar to humanize-duration.

README

Humanize Duration

I have the time in milliseconds and I want it to become "30 minutes" or "3 days, 1 hour". Enter Humanize Duration!

Basic usage

This package is available as humanize-duration in npm and Bower. You can also include the JavaScript in the browser.

In the browser:

<script src="humanize-duration.js"></script>
<script>
humanizeDuration(12000)
</script>

In Node (or Browserify or Webpack or anywhere with CommonJS):

var humanizeDuration = require("humanize-duration")
humanizeDuration(12000)

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(2015)      // "2.25 seconds"
humanizeDuration(97320000)  // "1 day, 3 hours, 2 minutes"

You can change the settings by passing options as the second argument:

humanizeDuration(3000, { language: "es" })  // "3 segundos"
humanizeDuration(5000, { language: "ko" })  // "5 초"

humanizeDuration(22140000, { delimiter: " and " })  // "6 hours and 9 minutes"
humanizeDuration(22140000, { delimiter: "--" })     // "6 hours--9 minutes"

humanizeDuration(260040000, { spacer: " whole " })  // "3 whole days, 14 whole minutes"
humanizeDuration(260040000, { spacer: "" })         // "3days, 14minutes"

humanizeDuration(1000000000000)                  // 31 years, 8 months, 1 week, 19 hours, 46 minutes, 40 seconds
humanizeDuration(1000000000000, { largest: 2 })  // 31 years, 8 month

humanizeDuration(3600000, { units: ["h"] })       // "1 hour"
humanizeDuration(3600000, { units: ["m"] })       // "60 minutes"
humanizeDuration(3600000, { units: ["d", "h"] })  // "1 hour"

humanizeDuration(1200)                   // "1.2 seconds"
humanizeDuration(1200, { round: true })  // "1 second"
humanizeDuration(1600, { round: true })  // "2 seconds"

humanizeDuration(1200)                          // "1.2 seconds"
humanizeDuration(1200, { decimal: ' point ' })  // "1 point 2 seconds"

humanizeDuration(3600000, {
  language: "es",
  units: ["m"]
})
// "60 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.

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

var shortEnglishHumanizer = humanizeDuration.humanizer({
  language: "shortEn",
  languages: {
    shortEn: {
      y: function() { return "y"; },
      mo: function() { return "mo"; },
      w: function() { return "w"; },
      d: function() { return "d"; },
      h: function() { return "h"; },
      m: function() { return "m"; },
      s: function() { return "s"; },
      ms: function() { return "ms"; },
    }
  }
})

shortEnglishHumanizer(15600000)  // "4 h, 20 m"

You can also add languages after initializing:

var humanizer = humanizeDuration.humanizer()

humanizer.languages.shortEn = {
  y: function(c) { return c + "y"; },
  // ...

Internally, the main humanizeDuration function is just a wrapper around a humanizer.

Supported languages

Humanize Duration supports the following languages:

Language	Code
Arabic	ar
Catalan	ca
Chinese, simplified	zh_CN
Chinese, traditional	zh_TW
Danish	da
Dutch	nl
English	en
French	fr
German	de
Hungarian	hu
Italian	it
Japanese	ja
Korean	ko
Norwegian	no
Polish	pl
Portuguese	pt
Russian	ru
Spanish	es
Swedish	sv
Turkish	tr
Ukrainian	uk

For a list of supported languages, you can use the getSupportedLanguages function.

humanizeDuration.getSupportedLanguages()
// ["ar", "ca", "da", "de" ...]

This function won't return any new langauges 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

Licensed under the WTFPL, so you can do whatever you want. Enjoy!

Changelog

3.2.1 / 2015-07-22

• fix: document largest option