Neverending Plethora of Modules
    Have ideas to improve npm?Join in the discussion! »

    duration-fns
    TypeScript icon, indicating that this package has built-in type declarations

    2.1.0 • Public • Published

    duration-fns

    A collection of JavaScript functions for working with durations.

    Installation

    npm install duration-fns

    Overview

    import * as duration from 'duration-fns'
    
    
    // Parsing / stringifying
    // ---------------------------------------------
    duration.parse('PT1M30S')
    // { minutes: 1, seconds: 30 }
    
    duration.toString({ years: 1, hours: 6 })
    // 'P1YT6H'
    
    
    // Conversion
    // ---------------------------------------------
    duration.toUnit({ minutes: 2 }, 'seconds') // 120
    duration.toMilliseconds({ seconds: 2 }) // 2000
    duration.toSeconds({ milliseconds: 2000 }) // 2
    duration.toMinutes({ hours: 1, seconds: 60 }) // 61
    duration.toHours({ minutes: 60 }) // 1
    duration.toDays({ weeks: 1, hours: 24 }) // 8
    duration.toWeeks({ days: 14 }) // 2
    duration.toMonths({ years: 2, months: 1 }) // 25
    duration.toYears({ months: 12 }) // 1
    
    
    // Normalizing
    // ---------------------------------------------
    duration.normalize({ days: 28, hours: 24 })
    // { days: 29 }
    
    duration.normalize({ days: 28, hours: 24 }, '2018-02-01')
    // { months: 1, days: 1 }
    
    duration.normalize({ days: 28, hours: 24 }, '2016-02-01')
    // { months: 1, days: 0 } (leap year)
    
    
    // Transformations
    // ---------------------------------------------
    duration.abs({ days: -1, seconds: 1 })
    // { days: 1, seconds: -1 }
    
    duration.negate({ days: -1, hours 2 })
    // { days: 1, hours: -2 }
    
    
    // Inspection
    // ---------------------------------------------
    duration.isNegative({ days: 1, hours: -25 })
    // true
    
    duration.isZero({ days: 1, hours: -24 })
    // true
    
    
    // Combining
    // ---------------------------------------------
    duration.subtract({ days: 2 }, { days: 1, hours: 12 })
    // { days: 1, hours: -12 }
    
    duration.sum({ days: 1 }, { days: 2, hours: 12 })
    // { days: 3, hours: 12 }
    
    
    // Date operations
    // ---------------------------------------------
    duration.apply('2020-01-01T00:00:00.000Z', { years: 2 }).toISOString()
    // '2022-01-01T00:00:00.000Z'
    
    duration.between('2022-01-01', '2020-01-01')
    // { years: -2 }
    
    
    // Meta
    // ---------------------------------------------
    duration.UNITS
    // A complete list of duration units, ordered from large to small:
    // ['years', 'months', 'weeks', 'days', ...]

    Conventions

    Function arguments

    All functions that accept a duration object also accept numbers and strings:

    duration.toSeconds({ minutes: 1 }); // 60
    duration.toSeconds(60000); // 60
    duration.toSeconds('PT1M'); // 60
    
    duration.sum({ seconds: 1 }, 'P1D', 200);
    // { days: 1, seconds: 1, milliseconds: 200 }

    Normalization

    Functions that transform or combine duration objects will not usually convert values between units:

    duration.sum({ seconds: 1 }, { milliseconds: 1000 });
    // { seconds: 1, milliseconds 1000 }

    Pass the return values through normalize for that functionality:

    duration.normalize({ seconds: 1, milliseconds 1000 });
    // { seconds: 2 }

    Some units cannot be normalized to others. For example, months can be normalized to years, but days cannot be normalized to months without a reference date:

    duration.normalize({ days: 31 });
    // { days: 31 }
    
    duration.normalize({ days: 31 }, '2020-02-01');
    // { months: 1, days: 2 }
    
    duration.normalize({ days: 31 }, '2020-12-01');
    // { months: 1, days: 0 }

    Misc

    Test coverage report. Netlify Status

    Install

    npm i duration-fns

    DownloadsWeekly Downloads

    2,457

    Version

    2.1.0

    License

    MIT

    Unpacked Size

    76 kB

    Total Files

    87

    Last publish

    Collaborators

    • avatar