intervalCountUnix

Signature

intervalCountUnix(start: string | number, end: string | number, unit: string): number

import { intervalCountUnix } from "@northguild/gmt/unix/interval";

Count how many unit boundaries a Unix epoch interval crosses.

• Counts local calendar boundaries touched by the half-open interval [start, end) — distinct from diffUnix, which measures exact elapsed duration.
• 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.
• Uses the system timeZone for calendar-unit boundaries (consistent with addUnix and splitIntervalByUnitUnix), so day/week/month/year counts are host-dependent.
• Weeks start on Monday (ISO 8601).
• Accepts singular or plural units ("day" and "days" behave identically).
• Returns null on invalid input (non-finite/non-integer start/end, start > end, unsupported unit, or invalid timeZone).

Parameters

Parameter	Type	Description
start	string | number	Unix epoch value (seconds or milliseconds) — interval start
end	string | number	Unix epoch value (seconds or milliseconds) — interval end
unit	string	unit string — any DateTimeUnit

Returns

number of unit boundaries touched, or null on invalid input

Examples

intervalCountUnix(0, 86400000, "hour") // 24
intervalCountUnix(1704153540000, 1704153660000, "day") // 2 (23:59 to 00:01 UTC)
intervalCountUnix(0, 0, "hour") // 0 (zero-length, on the boundary)
intervalCountUnix(1800000, 1800000, "hour") // 1 (zero-length, mid-hour)
intervalCountUnix(86400000, 0, "hour") // null
intervalCountUnix(NaN, 86400000, "hour") // null

Source

unix/interval/intervalCountUnix.ts