diffTime

Signature

diffTime(time1: string, time2: string, units: any, options?: RoundingOptions<Temporal.TimeUnit>): number | Record<TimeDurationUnit, number>

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

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

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

Parameters

Parameter	Type	Description
time1	string	ISO PlainTime string for the start
time2	string	ISO PlainTime string for the end
units	any	TimeDurationUnit | TimeDurationUnit[] to measure the difference
options	RoundingOptions<Temporal.TimeUnit>	optional: smallestUnit, roundingIncrement, roundingMode (Temporal.DifferenceOptions rounding controls)

Returns

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

Related types

• DurationUnit
• RoundingOptions
• TimeDurationUnit
• TimeUnit

Examples

diffTime("12:00:00", "14:30:00", "hour") // 2
diffTime("invalid", "14:30:00", "hour") // null

Source

plain/calculate/diffTime.ts