Intervals

A ZInterval is a span between two instants: a half-open range [start, end) over epoch nanoseconds. Intervals answer the questions schedules ask — does this overlap, what is the gap, split this by these points — as values, not loops.

import {ZInterval} from '@sajajs/zdate'

const hour = new ZInterval('2024-01-01T09:00:00Z', '2024-01-01T10:00:00Z')
const sinceNoon = new ZInterval('today noon', undefined)   // undefined endpoint means now

Endpoints accept anything a ZDate source string, ZDate, Date, or epoch bigint can express, and undefined means now. end must be greater than or equal to start; equal endpoints make an empty interval.

Properties

Member	Description
start / end	Epoch nanoseconds
empty	Whether the interval contains no time

Relations

Method	Description
contains(other?)	Point or interval containment
overlaps(other)	Any shared time
adjacent(other)	Touching without overlap
before(other) / after(other)	Strict ordering
equals(other)	Same span

Set Operations

Method	Returns
intersection(other)	ZInterval | null
union(other)	Combined interval
subtract(other)	ZInterval[] — zero, one, or two remainders
gap(other)	The interval between two disjoint intervals, or null
splitAt(...points)	ZInterval[] split at the given instants

Iteration

iterate() walks from start toward end by a step, excluding end. It advances with ZDate.by(), so steps are calendar- and time-zone-aware — leap years, month lengths, and DST included:

const interval = new ZInterval('2024-01-01T00:00:00Z', '2024-01-06T00:00:00Z')
const options = {zone: 'UTC', calendar: 'iso8601'} satisfies ViewOptions

for (const date of interval.iterate('1 day and 12 hours', options))
    console.log(date.format('iso'))

// 2024-01-01T00:00:00+00:00
// 2024-01-02T12:00:00+00:00
// 2024-01-04T00:00:00+00:00
// 2024-01-05T12:00:00+00:00

A step that fails to advance throws.

Measurement and Output

Method	Description
duration(viewOptions?)	The span as a ZDuration — calendar- and zone-aware via ZDate.diff(), always absolute
toISO() / toJSON() / toString()	ISO 8601 interval string (start/end)
ZInterval.parse(iso)	Parse an ISO interval: start/end, P…/end (duration/end), or start/P… (start/duration)