intervalLengthUtc

Signature

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

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

Return the exact length of a UTC interval in unit, as a real (possibly fractional) number.

• Distinct from intervalCountUtc, which counts calendar unit boundaries crossed rather than measuring exact duration — an interval from 23:59 to 00:01 touches 2 day boundaries via intervalCountUtc but has an exact length of ~0.0014 days via intervalLengthUtc.
• Boundaries are UTC boundaries — no DST is involved.
• Returns 0 for a zero-length interval (start === end).
• 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

exact length of the interval expressed in unit, or null on invalid input

Examples

intervalLengthUtc("2024-01-01T23:59:00Z", "2024-01-02T00:01:00Z", "day") // 0.001388888888888889
intervalLengthUtc("2024-01-01T23:59:00Z", "2024-01-02T00:01:00Z", "minute") // 2
intervalLengthUtc("2024-01-01T00:00:00Z", "2024-01-01T00:00:00Z", "day") // 0
intervalLengthUtc("invalid", "2024-01-02T00:00:00Z", "day") // null

Source

utc/interval/intervalLengthUtc.ts