diffDate

Signature

diffDate(date1: string, date2: string, unitArg: "years" | "months" | "weeks" | "days" | DateUnit | ("years" | "months" | "weeks" | "days" | DateUnit)[], options?: RoundingOptions<DateUnit>): number | Record<"years" | "months" | "weeks" | "days", number> | null

Return the difference between two PlainDate values using the provided unit.

• Returns null for invalid inputs (negative diffs are valid).
• Uses Temporal’s until semantics (TC39 CalendarDateUntil; for non-ISO calendars the Intl era/monthCode proposal’s NonISODateUntil, e.g. Buddhist Aug 31 to Sep 30 is 30 days, not a month) and extracts the requested unit.
• Accepts RFC 9557 calendar-annotated PlainDate strings (as convertDateToCalendar writes them). When date1 and date2 name the same calendar, the difference is measured in that calendar (a Hebrew leap year has 13 months). When they name different calendars (a bare ISO string names iso8601), the result is null, as TC39 DifferenceTemporalPlainDate throws when CalendarEquals is false.
• Compatibility: before 1.16.0 two different calendars were measured in ISO. To get that value, convert both to one calendar first: convertDateToCalendar(date, "iso8601"). smallestUnit, roundingIncrement, and roundingMode control optional rounding of the result, per Temporal’s DifferenceOptions — e.g. { smallestUnit: "week", roundingMode: "halfExpand" } rounds the difference to the nearest week before extracting the requested unit.
• When unitArg is an array, smallestUnit must not be coarser than the largest unit in the array (e.g. ["months", "days"] with smallestUnit: "year") — 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 }.
• Compatibility: since 1.16.0 calendar strings are RFC 9557 (ISO digits, [u-ca=<id>], canonical calendar ids); see isValidCalendarDate.

Parameters

Parameter	Type	Description
date1	string	ISO PlainDate string for the start, optionally calendar-annotated
date2	string	ISO PlainDate string for the end, optionally calendar-annotated
unitArg	"years" | "months" | "weeks" | "days" | DateUnit | ("years" | "months" | "weeks" | "days" | DateUnit)[]	date unit or units to measure the difference, singular or plural ("day" or "days"); a record result keeps the plural keys

Options

options

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

Type: RoundingOptions.

Option	Type	Default	Description
smallestUnit?	DateUnit | PluralUnit<DateUnit>	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

• DateDurationUnit
• RoundingOptions

Examples

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

diffDate("2024-03-10", "2024-03-15", "days") // 5

date1date2

output

 

Source

plain/calculate/diffDate.ts