intervalCountUtc

Signature

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

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

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 counts 1 when it sits mid-unit and 0 when it sits exactly on a unit boundary.
• 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

intervalCountUtc("2024-01-01T23:59:00Z", "2024-01-02T00:01:00Z", "day") // 2
intervalCountUtc("2024-01-01T00:00:00Z", "2024-01-03T00:00:00Z", "day") // 2
intervalCountUtc("2024-01-15T00:00:00Z", "2024-03-10T00:00:00Z", "month") // 3
intervalCountUtc("2024-01-01T05:00:00Z", "2024-01-01T05:00:00Z", "day") // 1 (zero-length, mid-day)
intervalCountUtc("2024-01-01T00:00:00Z", "2024-01-01T00:00:00Z", "day") // 0 (zero-length, on the boundary)
intervalCountUtc("invalid", "2024-01-02T00:00:00Z", "day") // null

Source

utc/interval/intervalCountUtc.ts