intervalLengthDate

Signature

intervalLengthDate(start: string, end: string, unit: string): number | null

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

• Distinct from intervalCountDate, which counts calendar unit boundaries crossed rather than measuring exact duration — see intervalCountDate’s JSDoc for the canonical 11:59pm→12:01am example of the two diverging. intervalLengthDate answers “how long is this interval”, intervalCountDate answers “how many boundaries does it touch”.
• Uses Temporal.Duration.prototype.total semantics, which resolve calendar units (month, year) against the interval’s own start so a partial month is expressed as a true fraction rather than truncated (non-ISO calendars follow the same TC39 NudgeToCalendarUnit steps over calendar-correct arithmetic).
• Returns 0 for a zero-length interval (start === end).
• 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 RFC 9557 calendar-annotated PlainDate strings — E5 (issue #78). When start and end carry the same calendar tag, the length is measured in that calendar; when they name different calendars the result is null — same calendar rule as intervalCountDate (TC39 CalendarEquals; before 1.16.0 measured in ISO).
• Compatibility: since 1.16.0 calendar strings are RFC 9557 (ISO digits, [u-ca=<id>], canonical calendar ids); see isValidCalendarDate.

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

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

Examples

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

intervalLengthDate("2024-01-01", "2024-01-03", "day") // 2

startendunit

output

 

Source

plain/interval/intervalLengthDate.ts