interval-set

A small TypeScript utility for set algebra over numeric intervals.

IntervalSet stores intervals in normalized form and supports adding intervals, subtraction, intersection, union, and conversion back to plain objects.

Interval Convention

Intervals are half open:

[start, end)

This includes start and excludes end.

For set coverage, touching intervals can be represented as one interval:

{ start: 1, end: 3 }
{ start: 3, end: 5 }

These normalize to:

{ start: 1, end: 5 }

Install From A Local Path

From another Node project:

npm install ../interval-set

Build this package before using it from another project:

npm run build

Basic Usage

import { IntervalSet } from "interval-set";

const set = new IntervalSet()
  .add({ start: 1, end: 5 })
  .add({ start: 10, end: 15 });

console.log(set.toArray());
// [
//   { start: 1, end: 5 },
//   { start: 10, end: 15 }
// ]

The constructor also accepts intervals:

const set = new IntervalSet([
  { start: 3, end: 5 },
  { start: 1, end: 3 },
]);

console.log(set.toArray());
// [{ start: 1, end: 5 }]

Methods

add(interval)

Adds an interval to the existing set, normalizes the internal intervals, and returns this for chaining.

const set = new IntervalSet()
  .add({ start: 1, end: 3 })
  .add({ start: 2, end: 6 });

console.log(set.toArray());
// [{ start: 1, end: 6 }]

subtract(B)

Returns a new IntervalSet containing all portions of this set not covered by B.

const a = new IntervalSet([{ start: 1, end: 10 }]);
const b = new IntervalSet([
  { start: 3, end: 5 },
  { start: 7, end: 8 },
]);

console.log(a.subtract(b).toArray());
// [
//   { start: 1, end: 3 },
//   { start: 5, end: 7 },
//   { start: 8, end: 10 }
// ]

intersect(B)

Returns a new IntervalSet containing the overlap between this set and B.

const a = new IntervalSet([{ start: 1, end: 5 }]);
const b = new IntervalSet([{ start: 3, end: 7 }]);

console.log(a.intersect(b).toArray());
// [{ start: 3, end: 5 }]

union(B)

Returns a new IntervalSet containing the normalized combination of this set and B.

const a = new IntervalSet([{ start: 1, end: 3 }]);
const b = new IntervalSet([{ start: 3, end: 5 }]);

console.log(a.union(b).toArray());
// [{ start: 1, end: 5 }]

toArray()

Returns a copy of the normalized intervals.

const set = new IntervalSet([{ start: 1, end: 5 }]);
const intervals = set.toArray();

intervals[0].start = 100;

console.log(set.toArray());
// [{ start: 1, end: 5 }]

Validation Rules

All intervals must satisfy:

start < end

Bounds must be finite numbers. Invalid bounds throw:

throw new TypeError("Interval bounds must be finite numbers.");

Intervals with start >= end throw:

throw new RangeError("Interval start must be less than interval end.");

Invalid intervals are rejected instead of being silently changed:

new IntervalSet([{ start: 10, end: 10 }]); // RangeError
new IntervalSet([{ start: 15, end: 10 }]); // RangeError
new IntervalSet([{ start: Number.NaN, end: 10 }]); // TypeError

Development

npm run build
npm run typecheck
npm test