mergeIntervalsZoned

Signature

mergeIntervalsZoned(intervals: { start: string; end: string; }[]): { start: string; end: string; }[]

Collapse a list of zoned intervals into the minimum set of non-overlapping intervals.

• List-form generalization of intervalUnionZoned, which is pairwise only.
• Comparison and merging use each interval’s instant, so intervals may carry different time zones.
• Intervals are half-open [start, end), the same rule as mergeIntervals. They are merged when they overlap or touch (one’s end is the same instant as the other’s start), so the runs returned never touch.
• An empty interval (start and end the same instant) holds no instant: it is absorbed when it touches or lies inside a run and dropped otherwise, so it never bridges a gap. A list of only empty intervals returns [], the same value as invalid input — use isValidCalendarZonedInterval to tell them apart.
• Order of the input list does not matter; the result is sorted by start instant. Each merged record’s start/end strings carry the time zone of whichever input interval contributed that boundary.
• Returns [] for an empty list.
• Returns [] when intervals is not an array, when any element is not a { start, end } record of valid ISO ZonedDateTime strings, or when any element has start > end or a leap-second string.
• Accepts RFC 9557 calendar-annotated zoned strings (as produced by convertZonedToCalendar) as well as bare ISO ones — E7 (issue #152) — but rejects a mismatched set: every endpoint in the list must name the same calendar system (E7’s D4-zoned). This function returns values the caller reads back as datetimes, and an array whose elements carried different calendar tags would be unreadable as a set. A mismatch returns [].
• Output boundaries are re-derived in the resolved calendar via formatZonedInCalendar, never copied from an input string (E7’s D7-zoned).

Parameters

Parameter	Type	Description
intervals	{ start: string; end: string; }[]	array of { start, end } records

Returns

the minimum set of non-overlapping { start, end } records, sorted by start, or [] on invalid input

Members of each item

Member	Type	Description
start	string	The instant the interval begins at, as a zoned ISO 8601 string with offset and bracketed time zone. It keeps a calendar annotation such as [u-ca=hebrew] when the inputs carry one.
end	string	The first instant after the interval, in the same format as start. It is exclusive: the interval holds everything from start up to but not including this value. It is always later than start.

Examples

import { mergeIntervalsZoned } from "@northguild/gmt/zoned/interval";

mergeIntervalsZoned([{ start: "2024-01-01T00:00:00+00:00[UTC]", end: "2024-01-10T00:00:00+00:00[UTC]" }, { start: "2024-01-05T00:00:00+00:00[UTC]", end: "2024-01-15T00:00:00+00:00[UTC]" }]) // [{ start: "2024-01-01T00:00:00+00:00[UTC]", end: "2024-01-15T00:00:00+00:00[UTC]" }]

intervals

×

×

+ add

output

 

Source

zoned/interval/mergeIntervalsZoned.ts