Skip to content
@northguild/gmt

intervalUnionDate

Playground

call
result 

Signature

Section titled “Signature”
intervalUnionDate(aStart: string, aEnd: string, bStart: string, bEnd: string): { start: string; end: string; }
import { intervalUnionDate } from "@northguild/gmt/plain/interval";

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

  • Uses Temporal.PlainDate.compare for comparison.
  • 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).
  • Accepts GMT 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

Section titled “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

Section titled “Returns”

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

Examples

Section titled “Examples”
intervalUnionDate("2024-01-01", "2024-06-30", "2024-04-01", "2024-12-31") // { start: "2024-01-01", end: "2024-12-31" }
intervalUnionDate("2024-01-01", "2024-06-30", "2024-06-30", "2024-12-31") // { start: "2024-01-01", end: "2024-12-31" }
intervalUnionDate("2024-01-01", "2024-06-30", "2024-07-01", "2024-12-31") // null
intervalUnionDate("invalid", "2024-06-30", "2024-04-01", "2024-12-31") // null
intervalUnionDate("5785-01-01[u-ca=hebrew]", "2024-06-30", "2024-04-01", "2024-12-31") // null (mismatched calendars)

Source

Section titled “Source”

plain/interval/intervalUnionDate.ts