Undercroft Labs LogoUndercroft Labs

Getting Started

Timespan is a lightweight, powerful library for working with time intervals in JavaScript and TypeScript. Whether you're measuring durations, formatting human-readable strings, or converting between time units — Timespan makes it effortless.

Why Use Timespan

  • Intuitive API with method chaining
  • Fluent conversion between time units
  • Works seamlessly in Node.js and the browser
  • Fully tested and production ready
  • Tiny bundle size (<4KB Brotli)

Installation

Install via your preferred package manager:

$ npm install @undercroft/timespan

Or load it from one of the available CDNs:

CDNLinkCopy
jsDelivrhttps://cdn.jsdelivr.net/npm/@undercroft/timespan/dist/index.umd.js
unpkghttps://unpkg.com/@undercroft/timespan/dist/index.umd.js
Skypackhttps://cdn.skypack.dev/@undercroft/timespan
esm.shhttps://esm.sh/@undercroft/timespan
jspmhttps://jspm.dev/@undercroft/timespan
esm.runhttps://esm.run/@undercroft/timespan

Usage in NodeJS

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

const span = new Timespan(new Date(), new Date());
console.log(span.toMilliseconds());

Usage in Browser

<script src="https://cdn.jsdelivr.net/npm/@undercroft/timespan/dist/index.umd.js"></script>
<script>
  const span = new window.Timespan(new Date(), new Date());
  console.log(span.toMilliseconds());
</script>

Creating Timespans

You can create a Timespan using either a string input or start/end dates.

From a string

const input = "3d 5h 30m";
const span = Timespan.fromString(input);

console.log(span.toString());   // "3d 5h 30m"
console.log(span.toHours());   // 77.5

From start and end dates

const start = new Date("2023-01-01");
const end = new Date("2023-01-15");

const span = new Timespan(start, end);
console.log(span.toDays()); // 14

Retrieving Timespan Information

const span = new Timespan(new Date("2023-01-01"), new Date("2023-01-15"));

console.log(span.start);           // 2023-01-01T00:00:00.000Z
console.log(span.end);             // 2023-01-15T00:00:00.000Z
console.log(span.toTimeframe());   // { weeks: 2, days: 0, ... }
console.log(span.toMilliseconds()); // 1209600000

Converting Timespans

const span = new Timespan(new Date("2023-01-01"), new Date("2023-01-15"));

console.log(span.toHours());   // 336
console.log(span.toWeeks());   // 2
console.log(span.toMonths());  // 0
console.log(span.toYears());   // 0

Static Creation Methods

Timespan.fromMilliseconds(5000);
Timespan.fromSeconds(120);
Timespan.fromMinutes(60);
Timespan.fromHours(24);
Timespan.fromDays(7);
Timespan.fromWeeks(4);
Timespan.fromMonths(6);
Timespan.fromYears(2);

Calculations & Comparisons

const span1 = Timespan.fromHours(12);
const span2 = Timespan.fromDays(2);

const added = span1.add(span2);
const subtracted = span2.subtract(span1);

const isEqual = span1.equals(span2);
const comparison = span1.compareTo(span2); // -1, 0, or 1

Contributing

Contributions are welcome! Feel free to open issues or submit pull requests on the GitHub repository.

License

Timespan is open source under the MIT License.