A simple Time Interval class developed for working with javascript date objects and relationships between them.

This package is written in Typescript, therefore there is no additional typing package needed to work with TS.

Install the package with NPM or yarn

npm i time-interval-js
-or-
yarn add time-interval-js

To import and use in your code:

import { TimeInterval } from 'time-interval-js'

And that's it.

Time Units:

const interval = TimeInterval.forOneHour();

interval.inHours(1); // 1

Comparison Based Constructor:

const date1 = new Date(2020-01-01);
const date2 = new Date(2020-01-02);

const intervalBetweenTwoDates = TimeInterval.fromTimeBetweenTwoDates(date1, date2);
// Produces a time interval equal to precisely the time between these two dates.

const interval = TimeInterval.forSpecifiedDays(2);

interval.inHours();  // 48
interval.inDays();  // 2
interval.inWeeks();  // 0.2857142857142857
// inHours()
// inDays()
// inSeconds()
// inMilliseconds()

Note: There is a getInApproximateYears method, but it is named this way because there is no guaranteed perfect precision. As we all know, years are not always 365 days, although the package uses this measure to calculate years.

const daysInterval = TimeInterval.fromSpecifiedDays(5);
const weeksInterval = TimeInterval.fromSpecifiedWeeks(2);

weeksInterval.isLongerThan(daysInterval) // true
daysInterval.isShorterThan(weeksInterval) // true

Want to calculate a date that is 5 weeks from now?

const now  = new Date();
const interval = TimeInterval.forSpecifiedWeeks(5);

interval.addToDate(now) // produces a new date that is exactly 5 weeks from the provided date.

The code is straightforward enough that you should be able to understand everything by looking at the single source file.

Check it out here.

There is also a TimeIntervalInterface available if you want to mock the object for any reason. The TimeInterval class implements this interface.

import { TimeIntervalInterface } from 'time-interval-js';

TL;DR: All Intervals are positive values.

This library operates on absolute time intervals. Theoretically speaking, a time interval has no negative or positive value, as it is only a relationship between two dates in time, and taking a stance from which point in time to view the difference (as positive or negative) is an additional property which the package currently does not support. Maybe later :)

Therefore, don't expect to get a negative value when you create a time interval between today and last week.

const lastWeek = new Date('2020-01-05');
const today = new Date('2020-01-12');

const interval = TimeInterval.fromTimeBetweenTwoDates(lastWeek, today);

interval.inSeconds()  // will ALWAYS be positive

All time intervals will have positive values. In the future perhaps we can add some specific methods which allow us to consider a perspective from which to judge the relationship between two points in time.