3.31.0 • Published 5 months ago

humanize-duration v3.31.0

Weekly downloads
308,934
License
Unlicense
Repository
github
Last release
5 months ago

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>

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.

Default: "en".

humanizeDuration(3000, { language: "es" });
// => "3 segundos"

humanizeDuration(5000, { language: "ko" });
// => "5 초"

fallbacks

Array of fallback languages, if the provided language cannot be found. Like language, accepts an ISO 639-1 code from one of the supported languages. It works from left to right, choosing the first language that's found.

Default: [].

humanizeDuration(3000, {
  language: "bad language",
  fallbacks: ["en"],
});
// => "3 seconds"

humanizeDuration(3000, {
  language: "bad language",
  fallbacks: ["another bad language", "es"],
});
// => "3 segundos"

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"]

humanizeDuration(69000, { units: ["h", "m", "s", "ms"] });
// => "1 minute, 9 seconds"

humanizeDuration(3600000, { units: ["h"] });
// => "1 hour"

humanizeDuration(3600000, { units: ["m"] });
// => "60 minutes"

humanizeDuration(3600000, { units: ["d", "h"] });
// => "1 hour"

largest

Integer representing the maximum number of units to use.

Default: Infinity

humanizeDuration(1000000000000);
// => "31 years, 8 months, 1 week, 19 hours, 46 minutes, 40 seconds"

humanizeDuration(1000000000000, { largest: 2 });
// => "31 years, 8 months"

round

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

Default: false

humanizeDuration(1200);
// => "1.2 seconds"

humanizeDuration(1200, { round: true });
// => "1 second"

humanizeDuration(1600, { round: true });
// => "2 seconds"

delimiter

String to display between units.

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

humanizeDuration(22140000);
// => "6 hours, 9 minutes"

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

spacer

String to display between the count and the word.

Default: " "

humanizeDuration(260040000);
// => "3 days, 14 minutes"

humanizeDuration(260040000, { spacer: " whole " });
// => "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.

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.

Default: ""

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

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

humanizeDuration(8123.456789);
// => "8.123456789 seconds"

humanizeDuration(8123.456789, { maxDecimalPoints: 3 });
// => "8.123 seconds"

humanizeDuration(8100, { maxDecimalPoints: 99 });
// => "8.1 seconds"

humanizeDuration(8000, { maxDecimalPoints: 99 });
// => "8 seconds"

humanizeDuration(7999, { maxDecimalPoints: 2 });
// => "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

humanizeDuration(1234);
// => "1.234 seconds"

humanizeDuration(1234, {
  digitReplacements: [
    "Zero",
    "One",
    "Two",
    "Three",
    "Four",
    "Five",
    "Six",
    "Seven",
    "Eight",
    "Nine",
  ],
});
// => "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 }

humanizeDuration(2629800000);
// => "1 month"

humanizeDuration(2629800000, {
  unitMeasures: {
    y: 31557600000,
    mo: 30 * 86400000,
    w: 604800000,
    d: 86400000,
    h: 3600000,
    m: 60000,
    s: 1000,
    ms: 1,
  },
});
// => "1 month, 10 hours, 30 minutes"

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:

LanguageCode
Afrikaansaf
Albaniansq
Arabicar
Basqueeu
Bengalibn
Bulgarianbg
Catalanca
Central Kurdishckb
Chinese, simplifiedzh_CN
Chinese, traditionalzh_TW
Croatianhr
Czechcs
Danishda
Dutchnl
Englishen
Esperantoeo
Estonianet
Faroesefo
Farsi/Persianfa
Finnishfi
Frenchfr
Germande
Greekel
Hebrewhe
Hindihi
Hungarianhu
Icelandicis
Indonesianid
Italianit
Japaneseja
Kannadakn
Khmerkm
Koreanko
Kurdishku
Laolo
Latvianlv
Lithuanianlt
Macedonianmk
Mongolianmn
Malayms
Marathimr
Norwegianno
Polishpl
Portuguesept
Romanianro
Russianru
Serbiansr
Slovaksk
Sloveniansl
Spanishes
Swahilisw
Swedishsv
Tamilta
Telugute
Thaith
Turkishtr
Ukrainianuk
Urduur
Uzbekuz
Uzbek (Cyrillic)uz_CYR
Vietnamesevi
Welshcy

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();
// => ["af", "ar", "bg", "bn", "ca", ...]

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

@bung87/media-meta@preply/navigationcasper-js-sdk-test-h2@goodware/log-dev@centreon/ui@salto-io/e2e-credentials-storevtms-subtitle-edit-ui@seasketch-sls-geoprocessing/clienttc-cli-plusdialer-reports@goodware/log-service@goodware/logger@goodware/loggingneo-fetchanthem-discord-botfiredragonimiassist-agentgql_din_modsimply-bot@zebrunner/reportingmetahkg@leni-msft/oavmbox-to-jsonbroken-link-checker-timeoutwavejs_builderscasperdask-js-sdk@leight-core/aiodjs-giveaway@clockbook-app/timetracker-module-server@aws/aws-codesuite-plugin-for-backstagecitymapexpand-react-bridgefexfetchtestcafemedia-meta@everything-registry/sub-chunk-1878pw-testmonitor-server-testmonsterenergymoonwalkerswap-default-token-listsmodmailbotmongo-fetch-apimominomylife-tradingnodebb-plugin-minecraft-integrationnodejs-infoairtap@xswap/token-lists@wmfs/lerna-sync@yatesdev/sineboard-datasource-drivetimealfred-chrome-workflow@zhenglaizhang/oavaboutnumber@zh0st/evm-chains@zebrajaeger/createpano@zf/jenkins-cliaf-tools-ts@younghappy/tilestrata@andrius-vet/wdio-timeline-reporteraptugoclientaxonv2sdk@andersbakken/fiskawesome-prettyaurelia-commonaurelia-timeaurelia-toolbeltbig-red@authereum/utilsasync-busasrtd@akromio/reporterastra-ufo-sdk@alexbradford3/wdio-timeline-reporter@alexbh/celocli@aws/amazon-ecs-plugin-for-backstage@aws/aws-codebuild-plugin-for-backstage@aws/aws-codepipeline-plugin-for-backstage@aws/aws-codeservices-plugin-for-backstage@backstage/plugin-azure-devops@backstage/plugin-code-climate@backstage/plugin-cicd-statistics@conorpai/tilestrata@conorpai/tilemantle@conorpai/tilemantle-tool@concepto/interface@backstage/plugin-ilert@backstage/plugin-circleci@backstage/plugin-scaffolder@backstage/plugin-scaffolder-react@behzadebrhm/utilsbosstrader@dal/dftr-app@dal/dftr-domain@cute-apocalypse/react-treecomfygure@d4data/mbox-parser@decentology/dappstarterconsole-functionscookiecordbroken-link-checker
3.31.0

5 months ago

3.30.0

6 months ago

3.29.0

9 months ago

3.28.0

1 year ago

3.27.3

2 years ago

3.27.2

2 years ago

3.27.1

2 years ago

3.27.0

3 years ago

3.26.0

3 years ago

3.25.2

3 years ago

3.25.1

3 years ago

3.25.0

3 years ago

3.24.0

3 years ago

3.23.1

4 years ago

3.23.0

4 years ago

3.22.0

4 years ago

3.21.0

5 years ago

3.20.1

5 years ago

3.20.0

5 years ago

3.19.0

5 years ago

3.18.0

5 years ago

3.17.0

5 years ago

3.16.0

5 years ago

3.15.3

6 years ago

3.15.2

6 years ago

3.15.1

6 years ago

3.15.0

6 years ago

3.14.0

6 years ago

3.13.0

6 years ago

3.12.1

6 years ago

3.12.0

6 years ago

3.11.0

6 years ago

3.10.1

7 years ago

3.10.0

7 years ago

3.9.1

8 years ago

3.9.0

8 years ago

3.8.0

8 years ago

3.7.1

8 years ago

3.7.0

8 years ago

3.6.1

8 years ago

3.6.0

8 years ago

3.5.0

8 years ago

3.4.0

8 years ago

3.3.0

9 years ago

3.2.1

9 years ago

3.2.0

9 years ago

3.1.0

9 years ago

3.0.0

9 years ago

2.8.0

9 years ago

2.7.0

9 years ago

2.6.1

9 years ago

2.6.0

9 years ago

2.5.0

9 years ago

2.4.0

9 years ago

2.3.0

9 years ago

2.2.1

9 years ago

2.2.0

9 years ago

2.1.0

9 years ago

2.0.1

10 years ago

2.0.0

10 years ago

1.1.1

10 years ago

1.1.0

10 years ago

1.0.0

10 years ago

0.9.0

10 years ago

0.8.2

10 years ago

0.8.1

10 years ago

0.8.0

10 years ago

0.6.1

10 years ago

0.6.0

10 years ago

0.5.0

10 years ago

0.4.1

10 years ago

0.4.0

10 years ago

0.3.0

10 years ago

0.2.0

11 years ago

0.1.0

11 years ago