Need private packages and team management tools?Check out npm Teams »

duration-fns

2.0.1 • 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.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 }

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

572

Version

2.0.1

License

MIT

Unpacked Size

59.6 kB

Total Files

66

Last publish

Collaborators

  • avatar