intervalDifferenceDate

Signature

intervalDifferenceDate(aStart: string, aEnd: string, bStart: string, bEnd: string): { start: string; end: string; }[]

import { intervalDifferenceDate } from "@northguild/gmt/plain/interval";

Return the portion(s) of interval A not covered by interval B.

• Uses Temporal.PlainDate.compare for comparison.
• Returns [] when B fully covers A.
• Returns [{ start, end }] when B overlaps one edge of A (or equals A).
• Returns [{ start, end }, { start, end }] when B is fully inside A with gaps on both sides.
• Returns [] if either interval is invalid (start > end).
• Returns [] on invalid input (wrong type, malformed strings).
• Accepts GMT calendar-annotated PlainDate strings — E5 (issue #78). Since the result is date values, all four arguments must carry the same calendar tag (or all be bare ISO); a mismatch returns [] (E5 decision of record D4). Each output piece’s tag is re-derived, 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

array of { start, end } records representing A minus B, or [] on invalid input / mismatched calendars

Examples

intervalDifferenceDate("2024-01-01", "2024-12-31", "2024-06-01", "2024-07-01") // [{ start: "2024-01-01", end: "2024-05-31" }, { start: "2024-07-02", end: "2024-12-31" }]
intervalDifferenceDate("2024-01-01", "2024-12-31", "2024-03-01", "2024-10-31") // [{ start: "2024-01-01", end: "2024-02-29" }, { start: "2024-11-01", end: "2024-12-31" }]
intervalDifferenceDate("2024-01-01", "2024-12-31", "2024-01-01", "2024-12-31") // []
intervalDifferenceDate("2024-01-01", "2024-12-31", "2024-06-01", "2024-12-31") // [{ start: "2024-01-01", end: "2024-05-31" }]
intervalDifferenceDate("invalid", "2024-12-31", "2024-06-01", "2024-07-01") // []

Source

plain/interval/intervalDifferenceDate.ts