compareDurations

Playground

valueother

call

result

 

Signature

compareDurations(a: string, b: string, options?: { relativeTo?: DurationRelativeTo; }): number

import { compareDurations } from "@northguild/gmt/duration/compare";

Compare two ISO 8601 duration strings by length.

• Uses Temporal.Duration.compare: -1 when a is shorter, 0 when equal, 1 when a is longer.
• Equality is by length, not by spelling — “PT60M” and “PT1H” compare 0, as do “P1D” and “PT24H” absent a relativeTo.
• relativeTo is required whenever a calendar unit (year/month/week) appears on either side; without it, returns null. Note the asymmetry with addDuration/subtractDuration (A2): Temporal.Duration.compare does accept relativeTo, while .add/.subtract do not, so calendar-unit durations are comparable here even though they cannot be combined there. durationAs and normalizeDuration (A3) carry the same relativeTo rule as this function.
• The anchor genuinely decides the answer rather than merely unblocking it: “P1M” is longer than “P30D” relative to January (31 days) and shorter relative to February 2024 (29).
• It matters for non-calendar units too when it names a zoned instant — across a DST spring-forward, “P1D” is 23 real hours and so compares shorter than “PT24H”.
• Returns null if either operand is not a valid ISO 8601 duration string, or relativeTo is invalid.

Parameters

Parameter	Type	Description
a	string	ISO 8601 duration string
b	string	ISO 8601 duration string

Options

options

Option	Type	Default
relativeTo?	DurationRelativeTo	—

Returns

-1, 0, or 1, or null on invalid input

Related types

• DurationRelativeTo

Examples

compareDurations("PT1H", "PT30M") // 1
compareDurations("PT60M", "PT1H") // 0
compareDurations("-PT1H", "PT1H") // -1
compareDurations("P1M", "P30D") // null (calendar unit needs relativeTo)
compareDurations("P1M", "P30D", { relativeTo: "2024-01-01" }) // 1
compareDurations("P1M", "P30D", { relativeTo: "2024-02-01" }) // -1
compareDurations("P1D", "PT24H", { relativeTo: "2024-03-10T00:00:00-05:00[America/New_York]" }) // -1 (spring-forward)
compareDurations("not a duration", "PT1H") // null
compareDurations("P1M", "P30D", { relativeTo: "5785-04-15[u-ca=hebrew]" }) // -1 (Tevet, a 29-day Hebrew month — relativeTo accepts GMT's calendar-annotated PlainDate string, not Temporal's own ISO-digit u-ca convention)

Source

duration/compare/compareDurations.ts