diffDateTimeAsDuration

Signature

diffDateTimeAsDuration(dateTime1: string, dateTime2: string, unit: DateTimeDurationUnit, options?: any): string

import { diffDateTimeAsDuration } from "@northguild/gmt/plain/calculate";

Return the difference between two PlainDateTime values as an ISO 8601 duration string,

• bridging to the duration namespace (see parseDuration, normalizeDuration).
• Returns "" for invalid inputs (negative diffs are valid and render with a leading -).
• Uses Temporal.PlainDateTime.until with largestUnit set to unit, then .toString().
• Unlike diffDateTime, 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. smallestUnit, roundingIncrement, and roundingMode control optional rounding of the underlying difference before it’s rendered, per Temporal’s DifferenceOptions — same as diffDateTime. 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
dateTime1	string	ISO PlainDateTime string for the start
dateTime2	string	ISO PlainDateTime string for the end
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

diffDateTimeAsDuration("2024-03-10T00:00:00", "2024-03-11T02:00:00", "days") // "P1DT2H"
diffDateTimeAsDuration("2024-03-11T02:00:00", "2024-03-10T00:00:00", "days") // "-P1DT2H"
diffDateTimeAsDuration("2024-01-01T00:00:00", "2024-01-01T00:00:00", "days") // "PT0S"
diffDateTimeAsDuration("invalid", "2024-03-15T12:00:00", "days") // ""
diffDateTimeAsDuration("2024-02-29T00:00:00", "2024-02-29T01:30:00", "hours", { smallestUnit: "hours", roundingMode: "halfExpand" }) // "PT2H"

Source

plain/calculate/diffDateTimeAsDuration.ts