Nobody's Perfect, Man

    humanize-duration
    DefinitelyTyped icon, indicating that this package has TypeScript declarations provided by the separate @types/humanize-duration package

    3.27.3 • Public • Published

    Humanize Duration

    npm version

    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-duration

    Basic 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 seconds

    unitMeasures

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

    Licensed under the permissive Unlicense. Enjoy!

    Related modules

    Install

    npm i humanize-duration

    DownloadsWeekly Downloads

    629,999

    Version

    3.27.3

    License

    Unlicense

    Unpacked Size

    65.9 kB

    Total Files

    6

    Last publish

    Collaborators

    • evanhahn