intervalOverlappingDaysUtc

Signature

intervalOverlappingDaysUtc(aStart: string, aEnd: string, bStart: string, bEnd: string): number

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

Return how many distinct UTC calendar dates two UTC intervals share.

• Counts the number of UTC dates touched by the closed intersection [max(aStart, bStart), min(aEnd, bEnd)] — inclusive of both endpoints.
• Boundaries are UTC boundaries — no DST is involved.
• Adjacent intervals (e.g. aEnd === bStart) share one date and count as 1.
• Returns 0 when the intervals do not overlap at all (a well-defined answer, not invalid input).
• Returns null if either interval is invalid (start > end).
• Returns null on invalid input (wrong type, malformed strings, leap seconds).
• Diverges from date-fns’s getOverlappingDaysInIntervals, which rounds up elapsed 24-hour periods instead of counting calendar dates (its own doc example — Jan 10-20 vs Jan 17-21 — returns 3 there, 4 here). To reproduce date-fns’s number, compose intervalIntersectionUtc with intervalCountUtc: const span = intervalIntersectionUtc(aStart, aEnd, bStart, bEnd); span ? intervalCountUtc(span.start, span.end, "day") : 0;

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

number of shared calendar dates, 0 when disjoint, or null on invalid input

Examples

intervalOverlappingDaysUtc("2024-01-01T23:59:00Z", "2024-01-02T00:01:00Z", "2024-01-01T23:59:00Z", "2024-01-02T00:01:00Z") // 2
intervalOverlappingDaysUtc("2024-01-01T00:00:00Z", "2024-01-02T00:00:00Z", "2024-01-02T00:00:00Z", "2024-01-03T00:00:00Z") // 1 (adjacent)
intervalOverlappingDaysUtc("2024-01-01T00:00:00Z", "2024-01-02T00:00:00Z", "2024-01-03T00:00:00Z", "2024-01-04T00:00:00Z") // 0 (disjoint)
intervalOverlappingDaysUtc("invalid", "2024-06-30T23:59:59Z", "2024-04-01T00:00:00Z", "2024-12-31T23:59:59Z") // null

Source

utc/interval/intervalOverlappingDaysUtc.ts