@musement/iso-duration
v1.0.0
Published
JS's library created to provide easy API for working with time duration. Based on ISO 8601. Inspired by [HumanizeDuration](https://github.com/EvanHahn/HumanizeDuration.js) and [ISO8601-duration](https://github.com/tolu/ISO8601-duration).
Downloads
3,886
Maintainers
Readme
@musement/iso-duration
JS's library created to provide easy API for working with time duration.
Based on ISO 8601.
Inspired by HumanizeDuration and ISO8601-duration.
Installation:
npm i @musement/iso-duration --save
Quick start:
// Import isoDuration and locales
import { isoDuration, en, pl, it } from '@musement/iso-duration'
// Setup locales
// key - string you want to use in `humanize` function
// value - IsoDuration i18n object.
isoDuration.setLocales(
{
en,
pl,
it,
},
{
fallbackLocale: 'en',
}
)
//Create duration object
const duration = isoDuration("P8DT30M")
// OR
const duration = isoDuration({
days: 8,
minutes: 30
})
//Get JS duration object
console.log(duration.parse())
// {
// weeks: 0,
// years: 0,
// months: 0,
// days: 8,
// hours: 0,
// minutes: 30,
// seconds: 0
// }
//Get duration ISO string
console.log(duration.toString())
// P8DT30M
//Humanize duration
console.log(duration.humanize('en'))
// 8 days 30 minutes
API:
Duration object supports:
- ISO_8601 duration string (
PnYnMnDTnHnMnS
,PnW
) - JS objects:
{
"weeks": Number,
"years": Number,
"months": Number,
"days": Number,
"hours": Number,
"minutes": Number,
"seconds": Number,
}
Example:
import { isoDuration } from '@musement/iso-duration@'
const durationFromString = isoDuration("P8DT30M")
const durationFromObj = isoDuration({
days: 8,
minutes: 30,
})
i18n
All languages which are expected to be available in .humanize
method needs to be loaded using isoDuration.setLocales
function. Currently, library provides support for languages listed under /src/locales
.
import { isoDuration, en, pl, it } from '@musement/iso-duration'
isoDuration.setLocales({
en,
pl,
it,
'en-GB': en,
'en-US': en,
})
Configuration
isoDuration.setLocales
can take an option
object as second argument (optional):
| Key | Type | Description | Default
| ---------------------- | -------- |-------------------------------------------------------------- | -----------
| fallbackLocale
| String | fallback locale used when an invalid locale is passed to IsoDuration.humanize
| undefined
IsoDuration object:
parse()
returnDurationObj
with all time periods represented as JS object
console.log(isoDuration("P8T30M").parse())
// {
// weeks: 0,
// years: 0,
// months: 0,
// days: 8,
// hours: 0,
// minutes: 30,
// seconds: 0
// }
toString()
returns ISO_8601 string:
console.log(isoDuration("P8T30M").toString())
// P8T30M
humanize(lang: string, config?: HumanizeConfig)
returns duration in human readable way:
⚠ Warning ️⚠ - usedlang
needs to be previously added to the library usingisoDuration.setLocales
console.log(isoDuration("P8T30M").humanize('en'))
// 8 hours 30 minutes
HumanizeConfig
Object:
{
largest: number
}
largest
- Reduce number of humanized to N the largest units:
console.log(
isoDuration({
years: 2,
months: 0,
days: 8,
hours: 20,
minutes: 30,
seconds: 15
}).humanize('en', { largest: 2 })
)
// 2 years 8 days
normalize(date?: Date)
returns normalized IsoDuration object:
console.log(isoDuration("PT90M").normalize().parse())
// PT1H30M
This method takes an optional argument date
which defines start of duration. It's used to correctly normalize number of days basing on corresponding month's length.
If it's not present normalize function will use current date (new Date()
) instead.
Month with 31 days:
console.log("Duration:", isoDuration("P31D").normalize(new Date(2020, 0, 1)).humanize('en'))
//Duration: 31 days
Month with 29 days:
console.log("Duration:", isoDuration("P31D").normalize(new Date(2020, 1, 1)).humanize('en'))
//Duration: 1 month 2 days
Credits
EvanHahn - author of HumanizeDuration
tolu author of ISO8601-duration