Timespan — Intuitive Time Interval Calculations in JavaScript

When dealing with time durations or intervals in JavaScript, it's often useful to have a reliable way to represent and manipulate them. The Timespan class provides a convenient and powerful solution for working with timespans in JavaScript.

Works in Typescript too!

UMD Support

Starting with version 1.1.0, you can use Timespan directly in the browser via the UMD build. All public methods are supported.

Distribution & Compatibility

• Small bundle footprint (<4kB brotli-compressed)
• Works in Node.js, modern browsers, and bundlers

Test Coverage & CI

• Full unit test coverage with Jest
• Automatically tested on Ubuntu and Windows
• Bundle size tracked via Size Limit
• Code coverage reported via Codecov

Breaking Changes (as of 1.1.0)

• Removed internal module access — All usage must go through the public Timespan export
• Internal validation and type guards added
• Removed legacy and deprecated utility modules

Installation

Usage in NodeJS

npm install @undercroft/timespan

Then use it like this.

import { Timespan } from '@undercroft/timespan';

Usage in Browser

<script src="https://cdn.jsdelivr.net/npm/@undercroft/timespan/dist/index.umd.js"></script>

Then use it like this.

<script>
  const span = new window.Timespan(new Date(), new Date());
  console.log(span.toMilliseconds());
</script>

Creating Timespans

To create a Timespan object, we can use the fromString method or directly instantiate it with start and end dates.

Creating a Timespan from a String

import { Timespan } from '@undercroft/timespan';

const input = '3d 5h 30m'; // Example input string representing a timespan
const timespan = Timespan.fromString(input);

console.log(timespan.toString()); // Output: '3d 5h 30m'
console.log(timespan.toHours()); // Output: 77.5

In the example above, we create a Timespan object from an input string using the fromString method. The input string specifies a timespan of 3 days, 5 hours, and 30 minutes. We then output the string representation of the timespan using toString() and calculate the total duration in hours using toHours().

Creating a Timespan with Start and End Dates

import { Timespan } from '@undercroft/timespan';

const start = new Date('2023-01-01');
const end = new Date('2023-01-15');
const timespan = new Timespan(start, end);

console.log(timespan.toDays()); // Output: 14

In this example, we create a Timespan object by providing the start and end dates directly. We then calculate the total duration in days using toDays().

Retrieving Timespan Information

The Timespan class provides various methods to retrieve information about a timespan.

import { Timespan } from '@undercroft/timespan';

const start = new Date('2023-01-01');
const end = new Date('2023-01-15');
const timespan = new Timespan(start, end);

// Output: 2023-01-01T00:00:00.000Z
console.log(timespan.start);

// Output: 2023-01-15T00:00:00.000Z
console.log(timespan.end);

// Output: { years: 0, months: 0, weeks: 2, days: 0, hours: 0, minutes: 0, seconds: 0, milliseconds: 0 }
console.log(timespan.toTimeframe());

// Output: 1209600000
console.log(timespan.toMilliseconds());

In the example above, we retrieve the start and end dates of the timespan using the start and end properties. We also obtain the timespan represented as a TimeFrame object using toTimeframe(), which provides the individual components of the timespan such as years, months, weeks, days, hours, minutes, seconds, and milliseconds. Lastly, we calculate the total duration in milliseconds using toMilliseconds().

Converting Timespans

The Timespan class provides convenient methods to convert a timespan to different units of time.

import { Timespan } from '@undercroft/timespan';

const start = new Date('2023-01-01');
const end = new Date('2023-01-15');
const timespan = new Timespan(start, end);

console.log(timespan.toHours()); // Output: 336
console.log(timespan.toWeeks()); // Output: 2
console.log(timespan.toMonths()); // Output: 0
console.log(timespan.toYears()); // Output: 0

In this example, we convert the timespan to various units such as hours, weeks, months, and years using the respective conversion methods.

More Examples of Creating TimeSpans

You can create a Timespan object using the static methods provided by the class. Here are the available methods:

Timespan.fromMilliseconds(milliseconds: number, startDate?: Date): Timespan Creates a Timespan object from a specified number of milliseconds.

import { Timespan } from '@undercroft/timespan';

const timespan = Timespan.fromMilliseconds(5000);
Timespan.fromSeconds(seconds, startDate);

Creates a Timespan object from a specified number of seconds.

import { Timespan } from '@undercroft/timespan';

const timespan = Timespan.fromSeconds(120);
Timespan.fromMinutes(minutes, startDate);

Creates a Timespan object from a specified number of minutes.

import { Timespan } from '@undercroft/timespan';

const timespan = Timespan.fromMinutes(60);
Timespan.fromHours(hours, startDate);

Creates a Timespan object from a specified number of hours.

import { Timespan } from '@undercroft/timespan';

const timespan = Timespan.fromHours(24);
Timespan.fromDays(days, startDate);

Creates a Timespan object from a specified number of days.

import { Timespan } from '@undercroft/timespan';

const timespan = Timespan.fromDays(7);
Timespan.fromWeeks(weeks, startDate);

Creates a Timespan object from a specified number of weeks.

import { Timespan } from '@undercroft/timespan';

const timespan = Timespan.fromWeeks(4);
Timespan.fromMonths(months, startDate);

Creates a Timespan object from a specified number of months.

import { Timespan } from '@undercroft/timespan';

const timespan = Timespan.fromMonths(6);
Timespan.fromYears(years, startDate);

Creates a Timespan object from a specified number of years.

import { Timespan } from '@undercroft/timespan';

const timespan = Timespan.fromYears(2);

Performing Calculations and Comparisons Once you have a Timespan object, you can perform various calculations and comparisons using the provided methods. Here are some examples:

import { Timespan } from '@undercroft/timespan';

const timespan1 = Timespan.fromHours(12);
const timespan2 = Timespan.fromDays(2);

const addedTimespan = timespan1.add(timespan2);
const subtractedTimespan = timespan2.subtract(timespan1);
const areEqual = timespan1.equals(timespan2);
const comparisonResult = timespan1.compareTo(timespan2);

Please refer to the API documentation, or the source code for more details on the available methods and their usage.

Contributing

Contributions to the Timespan class are welcome! If you find any issues or have suggestions for improvements, please open an issue or submit a pull request on the GitHub repository.

License

The Timespan class is licensed under the MIT License. See the LICENSE file for more information.