diffZonedAsDuration

Signature

diffZonedAsDuration(value1: string, value2: string, unit: DateTimeDurationUnit, options?: any): string

import { diffZonedAsDuration } from "@northguild/gmt/zoned/calculate";

Return the difference between two zoned datetimes as an ISO 8601 duration string,

• bridging to the duration namespace (see parseDuration, normalizeDuration).
• Uses Temporal.ZonedDateTime.until with largestUnit set to unit, then .toString().
• Converts both to UTC for consistent calculation, same as diffZoned.
• Accepts GMT calendar-annotated zoned strings, with the same shared-calendar-or-Gregorian- fallback policy as diffZoned (E7’s D5-zoned, issue #152).
• Unlike diffZoned, unit is a single unit (not an array) — an ISO duration string already expresses a full multi-unit breakdown via largestUnit alone, so there’s no array-of-units overload here.
• Returns "" for invalid input (negative diffs are valid and render with a leading -). smallestUnit, roundingIncrement, and roundingMode control optional rounding of the underlying difference before it’s rendered, per Temporal’s DifferenceOptions — same as diffZoned. toStringSmallestUnit, fractionalSecondDigits, and toStringRoundingMode control the precision of the rendered string itself, per Temporal’s ToStringPrecisionOptions (mirroring parseDuration’s options) — kept separate from the .until() rounding options above because both option sets have colliding smallestUnit/roundingMode keys with different Temporal types.

Parameters

Parameter	Type	Description
value1	string	zoned ISO 8601 datetime string (start), optionally calendar-annotated
value2	string	zoned ISO 8601 datetime string (end), optionally calendar-annotated
unit	DateTimeDurationUnit	DateTimeDurationUnit to use as the duration’s largestUnit
options	any	optional: smallestUnit, roundingIncrement, roundingMode (.until() rounding); toStringSmallestUnit, fractionalSecondDigits, toStringRoundingMode (.toString() precision)

Returns

ISO 8601 duration string, or “” on invalid input

Related types

• DurationUnit
• DateTimeDurationUnit
• TimeDurationUnit

Examples

diffZonedAsDuration("2024-03-09T12:00:00-05:00[America/New_York]", "2024-03-11T12:00:00-04:00[America/New_York]", "days") // "P1DT23H"
diffZonedAsDuration("2028-01-01T00:00:00+00:00[UTC]", "2028-01-01T00:00:00+00:00[UTC]", "hours") // "PT0S"
diffZonedAsDuration("invalid", "2028-01-01T00:00:00+00:00[UTC]", "days") // ""
diffZonedAsDuration("5784-01-01T00:00:00-04:00[u-ca=hebrew][America/New_York]", "5785-01-01T00:00:00-04:00[u-ca=hebrew][America/New_York]", "months") // "P13M" (Hebrew leap year)
diffZonedAsDuration("2024-03-10T14:30:00-04:00[America/New_York][u-ca=hebrew]", "2024-03-11T14:30:00-04:00[America/New_York]", "days") // "" (Temporal's segment ordering is not GMT's grammar)

Source

zoned/calculate/diffZonedAsDuration.ts