Interval.js

Interval.js is a small, typed library for closed numeric interval algebra. It provides containment, overlap, merging, subtraction, measurement, transformation, and set operations through a modern TypeScript class.

Use it for numeric ranges, scheduling coordinates, computational geometry, and Unix timestamp ranges. Calendar arithmetic and time zones remain a job for date-specific libraries.

Installation

Interval.js 0.1 requires Node.js 20 or newer and has no runtime dependencies.

npm install @rawify/interval

Quick Start

import Interval from '@rawify/interval';

const available = new Interval(0, 10);
const free = available.subtractAll([
  new Interval(3, 5),
  new Interval(8, 12),
]);

console.log(free.map(String)); // ['[0, 3]', '[5, 8]']
console.log(String(available)); // '[0, 10]'

CommonJS is supported as well:

const Interval = require('@rawify/interval');
const interval = new Interval(1, 5);

Interval Convention

Intervals use closed boundaries. A range [a, b] is considered empty when a >= b; invalid constructor input is normalized to [0, 0].

Interval.empty().isEmpty(); // true
new Interval(4, 4).isEmpty(); // true
new Interval(4, 2).equals(Interval.empty()); // true

Boundary containment remains closed, so new Interval(1, 4).isInside(4) is true. The intersection of touching ranges is a zero-length, and therefore empty, interval.

Queries

const interval = new Interval(2, 8);

interval.size();                         // 6
interval.midPoint();                     // 5
interval.isInside(3);                    // true
interval.containsInterval(new Interval(3, 7)); // true
interval.overlaps(new Interval(8, 10));  // true
interval.touches(new Interval(8, 10));   // true
interval.gap(new Interval(10, 12));      // 2

Available query methods are:

• isEmpty()
• size()
• midPoint()
• isInside(value)
• containsInterval(interval)
• equals(interval)
• overlaps(interval)
• touches(interval)
• gap(interval)
• compareTo(interval)

Set Operations

intersection(), union(), subtraction, and merge operations return new intervals and leave their inputs unchanged.

const left = new Interval(0, 6);
const right = new Interval(4, 10);

left.intersection(right); // [4, 6]
left.union(right);        // [0, 10]
left.subtract(right);     // [[0, 4]]

union() returns the convex hull, including any gap between disjoint inputs. Use mergeIfAdjacentOrOverlapping() when disjoint inputs should return null.

Normalize Ranges

mergeAll() clones, sorts, and merges overlapping or touching intervals:

const merged = Interval.mergeAll([
  new Interval(8, 10),
  new Interval(0, 3),
  new Interval(3, 6),
]);

console.log(merged.map(String)); // ['[0, 6]', '[8, 10]']

Subtract Multiple Ranges

const source = new Interval(0, 10);
const remainder = source.subtractAll([
  new Interval(2, 4),
  new Interval(6, 8),
]);

console.log(remainder.map(String)); // ['[0, 2]', '[4, 6]', '[8, 10]']

subtractSets() applies one normalized subtractor set to each source interval while preserving source order:

const result = Interval.subtractSets(
  [new Interval(0, 10), new Interval(20, 30)],
  [new Interval(3, 5), new Interval(8, 25)],
);

console.log(result.map(String)); // ['[0, 3]', '[5, 8]', '[25, 30]']

Other static set helpers are hull() and intersectionAll().

Transformations

Transform methods mutate and return the receiver for fluent use:

const moved = new Interval(0, 10)
  .translate(5)
  .extend(-1, 2)
  .scaleAroundMid(0.5);

Available transformations are:

• translate(delta)
• expandToInclude(value)
• extend(startDelta, endDelta)
• scaleAroundMid(factor)

Use clone() first when the original interval must remain unchanged.

Utilities

Interval.filterPoints(
  new Interval(1, 4),
  [0, 1, 2.5, 4, 7],
); // [1, 2.5, 4]

Interval.linearScale(
  new Interval(0, 10),
  new Interval(100, 200),
  2.5,
); // 125

Interval.sort(intervals) sorts its input array in place by start and then end. Other set helpers accept readonly arrays and return new arrays.

Browser Usage

The browser IIFE exposes a global Interval constructor and supports AMD loaders:

<script src="https://unpkg.com/@rawify/interval/dist/interval.min.js"></script>
<script>
  const interval = new Interval(1, 5);
</script>

The browser ESM build is available through the package export:

import Interval from '@rawify/interval/browser';

Published artifacts are:

• dist/interval.js: CommonJS
• dist/interval.mjs: ES module
• dist/interval.min.js: minified browser IIFE with AMD support
• dist/interval.min.mjs: minified browser ES module
• dist/interval.d.ts and dist/interval.d.mts: generated declarations

Development

npm install
npm test

npm test runs the strict TypeScript build, validates CommonJS and ESM type consumers, and executes the class and distribution suites.

License

Copyright (c) 2025-2026 Robert Eisele

Licensed under the MIT License.