A collection of JavaScript functions for working with durations.
npm install duration-fns
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', ...]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 }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 }