Interval.js

Interval.js is a lightweight JavaScript library for working with mathematical intervals, providing a wide range of operations useful in computational geometry, scheduling, numerical analysis and when using Unix timestamps also date ranges.

Features

• Basic interval operations: intersection, union, subtraction, merging
• Comparison and equality checks
• Query functions: overlap, containment, adjacency, distance (gap)
• Utility functions: size, midpoint, translation, scaling, extension
• Static helpers for merging and normalizing interval sets
• Designed for Closure Compiler advanced optimizations

Installation

You can install Interval.js via npm:

npm install @rawify/interval

Or with yarn:

yarn add @rawify/interval

Alternatively, download or clone the repository:

git clone https://github.com/rawify/Interval.js

Usage

Include the interval.min.js file in your project:

<script src="path/to/interval.min.js"></script>

Or in a Node.js project:

const Interval = require('@rawify/interval');

or

import Interval from '@rawify/interval';

Creating an Interval

Intervals can be created using the Interval constructor:

let i1 = new Interval(1, 5);
let i2 = new Interval(3, 7);

Empty intervals are represented by [0, 0].

Methods

intersection(i)

Finds the intersection of two intervals. Returns null if they don’t intersect.

let i1 = new Interval(1, 5);
let i2 = new Interval(3, 7);
let inter = i1.intersection(i2); // [3, 5]

union(i)

Returns the convex hull (minimal covering interval) of two intervals.

let uni = i1.union(i2); // [1, 7]

equals(i)

Checks if two intervals are equal.

i1.equals(new Interval(1, 5)); // true

overlaps(i)

Checks if two intervals overlap.

i1.overlaps(i2); // true

touches(i)

Checks if two intervals are adjacent (share a boundary point).

containsInterval(i)

Checks if the current interval fully contains another interval.

new Interval(1, 10).containsInterval(new Interval(3, 5)); // true

isInside(x)

Checks if a point x lies inside the interval.

isEmpty()

Returns true if the interval is empty (i.e. a >= b).

size()

Returns the length of the interval.

midPoint()

Returns the midpoint of the interval.

gap(i)

Computes the distance between two intervals (0 if overlapping or touching).

translate(dx)

Shifts the interval by dx.

extend(da, db)

Extends the start and end of the interval.

scaleAroundMid(f)

Scales the interval around its midpoint by factor f.

subtract(i)

Subtracts interval i from the current interval. May return up to two disjoint intervals.

subtractAll(list)

Subtracts multiple intervals, returning a normalized list of disjoint intervals.

toString()

Returns a string representation of the interval.

Static Methods

Interval.empty()

Creates an empty interval [0,0].

Interval.sort(list)

Sorts an array of intervals by start, then end.

Interval.mergeAll(list)

Merges overlapping or adjacent intervals in a list, returning disjoint intervals.

Interval.hull(list)

Returns the minimal covering interval of a list of intervals.

Interval.intersectionAll(list)

Computes the intersection of all intervals in a list.

Coding Style

As every library I publish, Interval.js is also built to be as small as possible after compressing it with Google Closure Compiler in advanced mode. Thus the coding style orientates a little on maxing-out the compression rate. Please make sure you keep this style if you plan to extend the library.

Building the library

After cloning the Git repository run:

npm install
npm run build

Copyright and Licensing

Copyright (c) 2025, Robert Eisele Licensed under the MIT license.