Skip to content
@northguild/gmt

intervalCountDate

Playground

call
result 

Signature

Section titled “Signature”
intervalCountDate(start: string, end: string, unit: string): number
import { intervalCountDate } from "@northguild/gmt/plain/interval";

Count how many unit boundaries a date interval crosses.

  • Counts calendar boundaries touched by the half-open interval [start, end) — distinct from diffDate, which measures exact elapsed duration.
  • "2024-01-01" to "2024-01-03" counted in days is 2: the end boundary is excluded.
  • A zero-length interval counts 1 when it sits mid-unit and 0 when it sits exactly on a unit boundary (e.g. "2024-01-15" counts 1 month but 0 days).
  • 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, or a unit that has no effect on PlainDate, e.g. "hours").
  • Accepts GMT calendar-annotated PlainDate strings — E5 (issue #78). When start and end carry the same calendar tag, boundaries are counted in that calendar (a Hebrew leap year crosses 13 month boundaries, not 12 — see the roadmap’s E5 decisions of record, D5). When they carry different tags (or either is bare ISO), counting falls back to Gregorian.

Parameters

Section titled “Parameters”
Parameter Type Description
start string ISO PlainDate string for the interval start, optionally calendar-annotated
end string ISO PlainDate string for the interval end, optionally calendar-annotated
unit string unit string — "year" | "month" | "week" | "day" (time units return null)

Returns

Section titled “Returns”

number of unit boundaries touched, or null on invalid input

Examples

Section titled “Examples”
intervalCountDate("2024-01-01", "2024-01-03", "day") // 2
intervalCountDate("2024-01-15", "2024-03-10", "month") // 3
intervalCountDate("2024-01-15", "2024-01-15", "month") // 1 (zero-length, mid-month)
intervalCountDate("2024-01-01", "2024-01-01", "month") // 0 (zero-length, on the boundary)
intervalCountDate("2024-01-01", "2024-01-10", "hour") // null
intervalCountDate("invalid", "2024-01-10", "day") // null
intervalCountDate("5784-01-01[u-ca=hebrew]", "5785-01-01[u-ca=hebrew]", "month") // 13 (Hebrew leap year, measured in Hebrew)

Source

Section titled “Source”

plain/interval/intervalCountDate.ts