intervalLengthZoned

Signature

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

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).
• Two values in different time zones (by TC39 TimeZoneEquals, so UTC equals Etc/UTC) can only be measured in time units: a calendar unit (day, week, month, year) returns null, as Temporal’s until throws, because day lengths differ between zones.
• Compatibility: before 1.16.0 a calendar unit across two zones returned a number. To measure such a pair, convert both ends to one zone first with convertZonedToZoned.
• Accepts RFC 9557 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 they name different calendars (a bare ISO string names iso8601) the result is null in every unit, "hour" included, as ZonedDateTime.prototype.until throws when TC39 CalendarEquals is false (before 1.16.0 it was measured in ISO).
• Returns null on invalid input (unparseable start/end, start > end, unsupported unit, leap-second strings).
• Compatibility: since 1.16.0 calendar strings are RFC 9557 (ISO digits, the [u-ca=<id>] annotation after the zone, canonical calendar ids); see isValidCalendarZonedDateTime.

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

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

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)

startendunit

output

 

Source

zoned/interval/intervalLengthZoned.ts