npm package: @rawify/interval
Description: The RAW Interval and Range library
Author: Robert Eisele
Latest version: 0.0.1

# Interval.js

[![NPM Package](https://img.shields.io/npm/v/@rawify/interval.svg?style=flat)](https://www.npmjs.com/package/@rawify/interval "View this project on npm")
[![MIT license](http://img.shields.io/badge/license-MIT-brightgreen.svg)](http://opensource.org/licenses/MIT)

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:

```bash
npm install @rawify/interval
````

Or with yarn:

```bash
yarn add @rawify/interval
```

Alternatively, download or clone the repository:

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

## Usage

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

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

Or in a Node.js project:

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

or

```javascript
import Interval from '@rawify/interval';
```

### Creating an Interval

Intervals can be created using the `Interval` constructor:

```javascript
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.

```javascript
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.

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

### `equals(i)`

Checks if two intervals are equal.

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

### `overlaps(i)`

Checks if two intervals overlap.

```javascript
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.

```javascript
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](https://raw.org/)
Licensed under the MIT license.