diffUnix

Signature

diffUnix(value1: number, value2: number, units: any, options?: any): number | Record<DateTimeDurationUnit, number>

import { diffUnix } from "@northguild/gmt/unix/calculate";

Return the difference between two Unix timestamps measured in the given 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	number	first Unix timestamp
value2	number	second Unix timestamp
units	any	DateTimeDurationUnit | DateTimeDurationUnit[] to measure the difference
options	any	optional: epochUnit (“seconds” | “milliseconds”), timeZone (IANA), smallestUnit, roundingIncrement, roundingMode (Temporal.DifferenceOptions rounding controls)

Returns

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

Related types

• DurationUnit
• DateTimeDurationUnit
• TimeDurationUnit

Examples

diffUnix(1706745600000, 1706659200000, "day") // 1
diffUnix(1706745600, 1706659200, "day", { epochUnit: "seconds" }) // 1
diffUnix(0, -86400000, "day") // 1 (Jan 1 1970 - Dec 31 1969 = 1 day)

Source

unix/calculate/diffUnix.ts