intervalCountUtc

Signature

intervalCountUtc(start: string, end: string, unit: string): number | null

Count how many unit boundaries a UTC interval crosses.

• Counts calendar boundaries touched by the half-open interval [start, end) — distinct from diffUtc, which measures exact elapsed duration. An interval from 23:59 to 00:01 is two minutes long but touches 2 day boundaries.
• The end boundary is excluded: midnight to midnight two days later counts 2 days.
• A zero-length interval (start === end) returns 0: the empty [start, start) holds no instant, so it touches no unit (before 1.16.0 it counted 1 when mid-unit).
• Boundaries are UTC boundaries — no DST is involved.
• Weeks start on Monday (ISO 8601).
• Accepts singular or plural units ("day" and "days" behave identically).
• Returns null on invalid input (unparseable start/end, start > end, unsupported unit, leap-second strings).

Parameters

Parameter	Type	Description
start	string	ISO UTC datetime string for the interval start
end	string	ISO UTC datetime string for the interval end
unit	string	unit string — any DateTimeUnit

Returns

number of unit boundaries touched, or null on invalid input

Examples

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

intervalCountUtc("2024-01-01T23:59:00Z", "2024-01-02T00:01:00Z", "day") // 2

startendunit

output

 

Source

utc/interval/intervalCountUtc.ts