Interval Algebra - Typescript

This is a reference implementation of the Springless Interval Specification repository. It adheres to the interval descriptions and conventions described therein.

It also borrows some inspirations and conventions from the Postgres Range library.

Implementation

Interval Representation

The core types used to represent an interval as implemented in this library are as follows:

/** only undefined is prohibited as a bound value */
export interface BoundType = {} | null;
/**
 * A bound consists of the value and a boolean indicating whether that bound is
 * included in the interval
 * */
export interface Bound<T extends BoundType> = [T, boolean];
export interface Interval<T extends BoundType> {
  /** The starting point of the interval */
  lower?: Bound<T>,
  /** The ending point of the interval */
  upper?: Bound<T>,
}

export type EmptyInterval = null;
export type UniversalInterval = Interval<never>;

Universal Set

The universal set is represented by the interval (,). This applies to both linear and cyclic intervals, in order to avoid ambiguous ad-hoc interval notations such as [5,5) (repurposing an otherwise invalid interval notation to mean 5 wrapping back around to 5) or the even more confusing combinatorial math that would give rise to such as [5,5) ∪ [7,7) = ???. For this reason any combination that would create a union of all possible values is simplified to just (,), in both interval types.

Upper and Lower in Cyclic Intervals

Typically there would be a strict lower <= upper constraint for set algebra, and while the cyclic interval of points on a circle could, for example, be expressed by going past 360 (375, 400, etc.), doing so as part of this library itself would require additional bounds checks and modulo math, along with tracking the max and min values and converting them every time they need to be compared.

Instead of that, this specification expects that you have already modulo'd the value prior to constructing the interval, and treats a situation where lower > upper as the interval "wrapping around" infinity and back through -infinity, and picks up from there. This removes the need for the library to even be aware of what the max and min values of the cyclic interval are, since none of the set math actually needs to reference it.

This does, however, mean that when you create a cyclic interval that "wraps around" back to the min value, you must actually set the upper bound to your minimum value (rather than undefined, which only extends to positive infinity).