intervalCountTime

Signature

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

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

Count how many unit boundaries a time interval crosses.

• Counts clock boundaries touched by the half-open interval [start, end) — distinct from diffTime, which measures exact elapsed duration. An interval from 12:59 to 13:01 is two minutes long but touches 2 hour boundaries.
• The end boundary is excluded: "12:00:00" to "14:00:00" counts 2 hours.
• A zero-length interval counts 1 when it sits mid-unit and 0 when it sits exactly on a unit boundary.
• Accepts singular or plural units ("hour" and "hours" behave identically).
• Returns null on invalid input (unparseable start/end, start > end, unsupported unit, or a unit that has no effect on PlainTime, e.g. "days").

Parameters

Parameter	Type	Description
start	string	ISO PlainTime string for the interval start
end	string	ISO PlainTime string for the interval end
unit	string	unit string — "hour" | "minute" | "second" | "millisecond" | "microsecond" | "nanosecond" (calendar units return null)

Returns

number of unit boundaries touched, or null on invalid input

Examples

intervalCountTime("12:00:00", "14:00:00", "hour") // 2
intervalCountTime("12:30:00", "13:00:00", "hour") // 1
intervalCountTime("12:30:00", "12:30:00", "hour") // 1 (zero-length, mid-hour)
intervalCountTime("12:00:00", "12:00:00", "hour") // 0 (zero-length, on the boundary)
intervalCountTime("12:00:00", "14:00:00", "day") // null
intervalCountTime("invalid", "14:00:00", "hour") // null

Source

plain/interval/intervalCountTime.ts