intervalLengthZoned

Signature

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

import { intervalLengthZoned } from "@northguild/gmt/zoned/interval";

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

• Distinct from intervalCountZoned, which counts local calendar unit boundaries crossed rather than measuring exact duration — a local day that springs forward touches 1 day boundary via intervalCountZoned but is exactly 23/24 ≈ 0.958 days via intervalLengthZoned.
• Uses Temporal.Duration.prototype.total with relativeTo set to start, so the result is DST-aware: dividing a spring-forward day’s length in hours returns 23, not 24.
• Returns 0 for a zero-length interval (start === end).
• Accepts GMT calendar-annotated zoned strings (as produced by convertZonedToCalendar) as well as bare ISO ones — E7 (issue #152). When BOTH endpoints carry the same calendar tag the measurement is made in that calendar; when the tags mismatch, or either endpoint is bare ISO, it falls back to Gregorian/ISO rather than returning the sentinel (E7’s D5-zoned). The fallback is mandatory, not a convenience: ZonedDateTime.prototype.until throws across mismatched calendars for EVERY largestUnit — verified, including "hour" and "nanosecond".
• Returns null on invalid input (unparseable start/end, start > end, unsupported unit, leap-second strings).

Parameters

Parameter	Type	Description
start	string	ISO 8601 zoned datetime string for the interval start
end	string	ISO 8601 zoned 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

intervalLengthZoned("2024-03-10T00:00:00-05:00[America/New_York]", "2024-03-11T00:00:00-04:00[America/New_York]", "hour") // 23 (spring forward)
intervalLengthZoned("2024-03-10T00:00:00-05:00[America/New_York]", "2024-03-11T00:00:00-04:00[America/New_York]", "day") // 1
intervalLengthZoned("2024-01-01T00:00:00+00:00[UTC]", "2024-01-01T00:00:00+00:00[UTC]", "day") // 0
intervalLengthZoned("invalid", "2024-01-02T00:00:00+00:00[UTC]", "day") // null

Source

zoned/interval/intervalLengthZoned.ts