diffUtc

Signature

diffUtc(value1: string, value2: string, units: any, options?: RoundingOptions<Temporal.DateTimeUnit>): number | Record<DateTimeDurationUnit, number>

import { diffUtc } from "@northguild/gmt/utc/calculate";

Return the difference between two UTC datetimes measured in the given date-time unit.

• Uses Temporal.Instant.until() to calculate the difference.
• Supports single unit or array of units.
• Returns null for invalid input. smallestUnit, roundingIncrement, and roundingMode control optional rounding of the result, per Temporal’s DifferenceOptions — e.g. { smallestUnit: "hour", roundingMode: "halfExpand" } rounds the difference to the nearest hour before extracting the requested unit.
• When units is an array, smallestUnit must not be coarser than the largest unit in the array (e.g. ["day", "hour"] with smallestUnit: "week") — this combination is rejected by Temporal and returns null, same as other invalid input.

Parameters

Parameter	Type	Description
value1	string	UTC ISO datetime string (start)
value2	string	UTC ISO datetime string (end)
units	any	DateTimeDurationUnit | DateTimeDurationUnit[] to measure the difference
options	RoundingOptions<Temporal.DateTimeUnit>	optional: smallestUnit, roundingIncrement, roundingMode (Temporal.DifferenceOptions rounding controls)

Returns

numeric difference in the requested unit, or null on invalid input

Related types

• DurationUnit
• DateTimeDurationUnit
• DateTimeUnit
• RoundingOptions
• TimeDurationUnit
• TimeUnit

Examples

diffUtc("2024-03-10T12:00:00Z", "2024-03-11T12:00:00Z", "hour") // 24
diffUtc("2024-03-10T12:00:00Z", "2025-04-10T12:00:00Z", ["year", "month"]) // { year: 1, month: 1 }
diffUtc("invalid", "2024-03-11T12:00:00Z", "hour") // null

Source

utc/calculate/diffUtc.ts