diffDateTime

Signature

diffDateTime(dateTime1: string, dateTime2: string, units: any, options?: RoundingOptions<Temporal.DateTimeUnit>): number | Record<DateTimeDurationUnit, number>

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

Return the difference between two PlainDateTime values in the requested unit.

• Returns null for invalid inputs (negative diffs are valid).
• Uses Temporal.PlainDateTime.until and extracts the requested unit. 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
dateTime1	string	ISO PlainDateTime string for the start
dateTime2	string	ISO PlainDateTime string for the 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

diffDateTime("2024-03-10T12:00:00", "2024-03-15T12:00:00", "day") // 5
diffDateTime("invalid", "2024-03-15T12:00:00", "day") // null

Source

plain/calculate/diffDateTime.ts