@burglekitt/gmt/dist/zoned/interval/intervalLengthZoned.d.ts

Temporal-based date and time utilities with timezone support and polyfill integration

/**
 * 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).
 *
 * @param start ISO 8601 zoned datetime string for the interval start
 * @param end ISO 8601 zoned datetime string for the interval end
 * @param unit unit string — any `DateTimeUnit`
 * @returns exact length of the interval expressed in `unit`, or null on invalid input
 *
 * @example 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)
 * @example intervalLengthZoned("2024-03-10T00:00:00-05:00[America/New_York]", "2024-03-11T00:00:00-04:00[America/New_York]", "day") // 1
 * @example intervalLengthZoned("2024-01-01T00:00:00+00:00[UTC]", "2024-01-01T00:00:00+00:00[UTC]", "day") // 0
 * @example intervalLengthZoned("invalid", "2024-01-02T00:00:00+00:00[UTC]", "day") // null
 */
export declare function intervalLengthZoned(start: string, end: string, unit: string): number | null;