diffDateTime

Signature

diffDateTime(dateTime1: string, dateTime2: string, units: keyof DurationLike | DateTimeUnit | (keyof DurationLike | DateTimeUnit)[], options?: RoundingOptions<DateTimeUnit>): number | Record<keyof DurationLike, number> | null

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. ["days", "hours"] with smallestUnit: "week") — this combination is rejected by Temporal and returns null, same as other invalid input.
• With an array of units, the record is the whole difference: the largest listed unit is Temporal’s largestUnit, and the amount of each unlisted unit between two listed units is carried into the next smaller listed unit, measured from the start moved by the larger listed amounts (so adding the record to the start reaches the end). Units smaller than the smallest listed unit are truncated, as for a single unit. For example, ["years", "days"] over 1 year 59 days returns { years: 1, days: 59 }.
• Nanosecond precision: the result is a JavaScript number, so it stops being exact once it passes Number.MAX_SAFE_INTEGER — about 104 days in nanoseconds and about 285 years in microseconds. diffDateTime("2024-01-01T00:00:00", "2024-04-15T00:00:00.000000001", "nanoseconds") returns 9072000000000000 rather than 9072000000000001. For an exact count use the bigint APIs: spanNs in span/, or toNanoseconds in precision/.

Parameters

Parameter	Type	Description
dateTime1	string	ISO PlainDateTime string for the start
dateTime2	string	ISO PlainDateTime string for the end
units	keyof DurationLike | DateTimeUnit | (keyof DurationLike | DateTimeUnit)[]	DateTimeDurationUnit | DateTimeDurationUnit[] to measure the difference

Options

options

optional: how the difference is rounded; a non-object value (such as null) is invalid

Type: RoundingOptions.

Option	Type	Default	Description
smallestUnit?	DateTimeUnit | PluralUnit<DateTimeUnit>	None. The difference is not rounded: Temporal uses the smallest unit the values have, "day" for dates and "nanosecond" otherwise.	The smallest unit kept in the difference; anything smaller is rounded into it. It may not be larger than the largest unit asked for.
roundingIncrement?	number	1, Temporal’s default.	The step the smallest unit is rounded to, so 15 with "minute" rounds to a quarter of an hour. For a time unit it must divide the next larger unit evenly and be smaller than it (15 or 30 minutes, not 7 or 60); a date unit takes any whole number from 1 up. A non-integer is truncated first, as Temporal does, and any other value is invalid input.
roundingMode?	"ceil" | "floor" | "expand" | "trunc" | "halfCeil" | "halfFloor" | "halfExpand" | "halfTrunc" | "halfEven"	"trunc", Temporal’s default for a difference.	Which way a value between two steps goes. "trunc" rounds toward zero and "halfExpand" to the nearest step, a half going away from zero; the other modes are those of Temporal’s roundingMode option.

Returns

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

Related types

• DateTimeDurationUnit
• RoundingOptions

Examples

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

diffDateTime("2024-03-10T12:00:00", "2024-03-15T12:00:00", "days") // 5

dateTime1dateTime2

output

 

Source

plain/calculate/diffDateTime.ts