intervalUnionZoned

Signature

intervalUnionZoned(aStart: string, aEnd: string, bStart: string, bEnd: string): { start: string; end: string; } | null

Return the combined span of two half-open zoned intervals [start, end), or null when their union is not one non-empty span.

• Uses Temporal.ZonedDateTime.compare for comparison (same instant semantics).
• The result is the single run mergeIntervalsZoned([a, b]) produces, the same rule as mergeIntervals. Overlapping intervals return their merged span, and each boundary keeps the time zone of the interval that contributed it.
• Touching intervals (e.g. aEnd the same instant as bStart) leave no gap between them and ARE merged.
• An empty interval (start and end the same instant) holds no instant, so it never changes the result: with a non-empty interval the answer is that interval, and two empty intervals give null.
• Returns null if either interval is invalid (start > end).
• Returns null on invalid input (wrong type, malformed strings, leap seconds).
• Accepts RFC 9557 calendar-annotated zoned strings (as produced by convertZonedToCalendar) as well as bare ISO ones — E7 (issue #152) — but rejects a mismatched pair: every endpoint must name the same calendar system (E7’s D4-zoned). Unlike the ordering functions, this one returns a value the caller reads back as a datetime, and there is no principled way to pick one endpoint’s calendar as the answer’s. Rejection also keeps a uniform policy across all eight value-returning zoned set operations, four of which return arrays — a per-element “winner’s tag” would produce a result set whose members disagree about which calendar they are in. (intervalUnionZoned’s existing “winning endpoint’s time zone wins” is not precedent: the zone is a property of the surviving point, the calendar is a property of the answer.) A mismatch returns the sentinel.
• Output boundaries are re-derived in the resolved calendar via formatZonedInCalendar, never copied from an input string (E7’s D7-zoned).
• Rejects a calendar annotation before the time zone annotation, which is not RFC 9557.

Parameters

Parameter	Type	Description
aStart	string	ISO 8601 zoned datetime string for the first interval start
aEnd	string	ISO 8601 zoned datetime string for the first interval end
bStart	string	ISO 8601 zoned datetime string for the second interval start
bEnd	string	ISO 8601 zoned datetime string for the second interval end

Returns

{ start, end } with the merged span, or null on invalid input / disjoint intervals

Members

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 { intervalUnionZoned } from "@northguild/gmt/zoned/interval";

intervalUnionZoned("2024-01-01T00:00:00+00:00[UTC]", "2024-06-30T23:59:59+00:00[UTC]", "2024-04-01T00:00:00+00:00[UTC]", "2024-12-31T23:59:59+00:00[UTC]") // { start: "2024-01-01T00:00:00+00:00[UTC]", end: "2024-12-31T23:59:59+00:00[UTC]" }

aStartaEndbStartbEnd

output

 

Interval algebra visualizer

1. Place two intervals

A

B

Intersection

Union

Difference (A − B)

Symmetric difference (XOR)

Jan 2024JulDec

A startA end

B startB end

2. Compare the four operations

Intersection

 

Union

 

Difference (A − B)

 

Symmetric difference (XOR)

 

Source

zoned/interval/intervalUnionZoned.ts