@musement/iso-duration

JS's library created to provide an easy API for working with time duration.
Based on ISO 8601.
Inspired by HumanizeDuration and ISO8601-duration.

Installation

npm i @musement/iso-duration --save

Getting started

1// Import isoDuration and locales
2import { isoDuration, en, pl, it } from '@musement/iso-duration';
3
4// Setup locales
5isoDuration.setLocales(
6  {
7    en,
8    pl,
9    it,
10  },
11  {
12    fallbackLocale: 'en',
13  }
14);
15
16//Create duration object
17const duration = isoDuration("P8DT30M");
18// OR
19const duration = isoDuration({
20  days: 8,
21  minutes: 30
22});
23
24//Get JS duration object
25console.log(duration.parse());
26// {
27//   weeks: 0,
28//   years: 0,
29//   months: 0,
30//   days: 8,
31//   hours: 0,
32//   minutes: 30,
33//   seconds: 0
34// }
35
36//Get duration ISO string
37console.log(duration.toString());
38// P8DT30M
39
40//Humanize duration 
41console.log(duration.humanize('en'));
42// 8 days 30 minutes

API

isoDuration.setLocales(obj: Locales, options?: LocalesOptions)

You need to initialize the languages you want to use in .humanize(lang), using the isoDuration.setLocales function. Currently, the library provides support for languages listed under /src/locales.

Languages not imported by your application will be removed by the module bundler (ex. webpack) during a build process using a tree-shaking mechanism.

1import { isoDuration, en, pl, it } from '@musement/iso-duration';
2
3// isoDuration.setLocales(locales, localesOptions);
4isoDuration.setLocales({
5  en,
6  pl,
7  it,
8  'en-GB': en,
9  'en-US': en,  
10}, {
11  fallbackLocale: 'en'
12});

LocalesOptions parameter (optional)

1interface LocalesOptions {
2  fallbackLocale: string
3};

Key	Type	Description	Default
fallbackLocale	String	locale which needs to be when IsoDuration.prototype.humanize(lang: string) received incorrect parameter	undefined

isoDuration(duration: string | Partial<DurationObj>): IsoDuration

Supported duration types :

• ISO_8601 duration string (PnYnMnDTnHnMnS, PnW)
• JS objects (matching Partial<DurationObj> interface)

1interface DurationObj {
2  "weeks": number,
3  "years": number,
4  "months": number,
5  "days": number,
6  "hours": number,
7  "minutes": number,
8  "seconds": number,
9};

Example:

1import { isoDuration } from '@musement/iso-duration';
2
3const durationFromString = isoDuration("P8DT30M");
4const durationFromObj = isoDuration({
5  days: 8,
6  minutes: 30,
7});

IsoDuration.prototype.parse()

Returns JS DurationObj

1console.log(isoDuration("P8T30M").parse());
2// {
3//   weeks: 0,
4//   years: 0,
5//   months: 0,
6//   days: 8,
7//   hours: 0,
8//   minutes: 30,
9//   seconds: 0
10// }

IsoDuration.prototype.toString()

Returns ISO_8601 string:

1console.log(isoDuration("P8T30M").toString());
2// P8T30M

IsoDuration.prototype.humanize(lang: string, config?: HumanizeConfig)

Returns duration in a human-readable way.
⚠ Warning ⚠ - used lang needs to be previously added to the library using isoDuration.setLocales()

1console.log(isoDuration("P8T30M").humanize('en'));
2// 8 hours 30 minutes

HumanizeConfig parameter (optional):

1interface HumanizeConfig {
2  largest: number
3};

Key	Type	Description	Default
largest	Number	Humanize only n largest duration values.	undefined

1console.log(
2  isoDuration({
3    years: 2,
4    months: 0,
5    days: 8,
6    hours: 20,
7    minutes: 30,
8    seconds: 15
9  }).humanize('en', { largest: 2 })
10);
11// 2 years 8 days

IsoDuration.prototype.normalize(date?: Date)

returns normalized IsoDuration object:

1console.log(isoDuration("PT90M").normalize().toString());
2// PT1H30M

This method takes an optional date argument which defines the start of the duration. It's used to correctly normalize the number of days basing on the corresponding month's length. If it's not present normalize function will use the current date (new Date()) instead.

Month with 31 days:

1console.log("Duration:", isoDuration("P31D").normalize(new Date(2020, 0, 1)).humanize('en'));
2//Duration: 31 days

Month with 29 days:

1console.log("Duration:", isoDuration("P31D").normalize(new Date(2020, 1, 1)).humanize('en'));
2//Duration: 1 month 2 days

Credits

EvanHahn - author of HumanizeDuration
tolu author of ISO8601-duration