intervalUnionUtc

Signature

intervalUnionUtc(aStart: string, aEnd: string, bStart: string, bEnd: string): { start: string; end: string; }

import { intervalUnionUtc } from "@northguild/gmt/utc/interval";

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

• Uses Temporal.Instant.compare for comparison (same instant semantics).
• Overlapping intervals return their merged span.
• Adjacent intervals (e.g. aEnd === bStart) share one instant and ARE merged.
• Returns null if either interval is invalid (start > end).
• Returns null on invalid input (wrong type, malformed strings, leap seconds).

Parameters

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

Returns

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

Examples

intervalUnionUtc("2024-01-01T00:00:00Z", "2024-06-30T23:59:59Z", "2024-04-01T00:00:00Z", "2024-12-31T23:59:59Z") // { start: "2024-01-01T00:00:00Z", end: "2024-12-31T23:59:59Z" }
intervalUnionUtc("2024-01-01T00:00:00Z", "2024-06-30T23:59:59Z", "2024-06-30T23:59:59Z", "2024-12-31T23:59:59Z") // { start: "2024-01-01T00:00:00Z", end: "2024-12-31T23:59:59Z" }
intervalUnionUtc("2024-01-01T00:00:00Z", "2024-06-30T23:59:59Z", "2024-07-01T00:00:00Z", "2024-12-31T23:59:59Z") // null
intervalUnionUtc("invalid", "2024-06-30T23:59:59Z", "2024-04-01T00:00:00Z", "2024-12-31T23:59:59Z") // null

Source

utc/interval/intervalUnionUtc.ts