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!

Usage

To use it in the browser:

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

To use in Node or Browserify (after installing the package):

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

Here's some basic usage:

humanizeDuration(1)         // "1 millisecond"
humanizeDuration(3000)      // "3 seconds"
humanizeDuration(2012)      // "2 seconds, 12 milliseconds"
humanizeDuration(97320000)  // "1 day, 3 hours, 2 minutes"

You can also change the language:

humanizeDuration(3000, "es")  // "3 segundos"

humanizeDuration.language = "fr"  // change language to French
humanizeDuration(3000)            // "3 secondes"
humanizeDuration(5000, "ko")      // "5 초"
humanizeDuration.language = "en"  // change language back to English

You can also get the components of the humanizization, using componentsOf:

var components = humanizeDuration.componentsOf(97320000);
// components.days == "1 day"
// components.total.days == "1 day"
// components.hours == "3 hours"
// components.total.hours == "27 hours"
// components.seconds == "0 seconds"
// components.total.seconds == "97320 seconds"

Some edge cases:

humanizeDuration(12.34) // "12.34 milliseconds"
humanizeDuration(-567)  // "567 milliseconds", ignores negative numbers

humanizeDuration(new Number(8910)) // works as normal

Supported languages

Humanize Duration supports the following languages:

• Catalan (ca)
• Danish (da)
• English (en)
• French (fr)
• German (de)
• Korean (ko)
• Norwegian (nob)
• Polish (pl)
• Portuguese (pt)
• Spanish (es)

Credits

Lovingly made by Evan Hahn with language support by Martin Prins. Thanks to Filipi Siqueira for Portuguese support, Peter Rekdal Sunde for Norwegian support, and Michał Janiec for Polish support.

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

Enjoy!