intervalUnionDate

Signature

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

Return the combined span of two date intervals, or null when they are disjoint.

• Uses Temporal.PlainDate.compare for comparison.
• Half-open: an interval holds every t with start <= t < end. The union is returned only when it is one non-empty interval — the single run CORE-6’s mergeIntervals would give.
• Overlapping intervals, and touching intervals (aEnd === bStart), return their combined span.
• Two non-empty intervals with any gap between them return null, even a one-unit gap. The caveat matters: an empty interval is the empty set, so it is never “separated” from anything. A non-empty interval unioned with an empty one far away is still that non-empty interval — see the next bullet — not null.
• An empty interval (start === end) is the empty set: it adds nothing, so the union is the other interval. Two empty intervals have no non-empty union and return null.
• Returns null if either interval is invalid (start > end).
• Returns null on invalid input (wrong type, malformed strings).
• Accepts RFC 9557 calendar-annotated PlainDate strings — E5 (issue #78). Since the result is a date value, all four arguments must carry the same calendar tag (or all be bare ISO); a mismatch returns null rather than guessing an output calendar (E5 decision of record D4). The output’s tag is re-derived from the merged span, never copied from an input.

Parameters

Parameter	Type	Description
aStart	string	ISO 8601 date string for the first interval start, optionally calendar-annotated
aEnd	string	ISO 8601 date string for the first interval end, optionally calendar-annotated
bStart	string	ISO 8601 date string for the second interval start, optionally calendar-annotated
bEnd	string	ISO 8601 date string for the second interval end, optionally calendar-annotated

Returns

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

Members

Member	Type	Description
start	string	The date the interval begins on, as an ISO 8601 date (YYYY-MM-DD). It keeps a calendar annotation such as [u-ca=hebrew] when the inputs carry one.
end	string	The first date 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 { intervalUnionDate } from "@northguild/gmt/plain/interval";

intervalUnionDate("2024-01-01", "2024-06-30", "2024-04-01", "2024-12-31") // { start: "2024-01-01", end: "2024-12-31" }

aStartaEndbStartbEnd

output

 

Source

plain/interval/intervalUnionDate.ts