@musement/iso-duration
    TypeScript icon, indicating that this package has built-in type declarations

    1.0.0 • Public • Published

    @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() return DurationObj 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 ️ - used lang needs to be previously added to the library using isoDuration.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

    Install

    npm i @musement/iso-duration

    DownloadsWeekly Downloads

    543

    Version

    1.0.0

    License

    ISC

    Unpacked Size

    93.1 kB

    Total Files

    65

    Last publish

    Collaborators

    • cronzio
    • przemkow
    • marcozi