Skip to content
@northguild/gmt

diffDate

Playground

call
result 

Signature

Section titled “Signature”
diffDate(date1: string, date2: string, unitArg: any, options?: RoundingOptions<Temporal.DateUnit>): number | Record<DateDurationUnit, number>
import { diffDate } from "@northguild/gmt/plain/calculate";

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

  • Returns null for invalid inputs (negative diffs are valid).
  • Uses Temporal.PlainDate.until and extracts the requested unit.
  • Accepts GMT calendar-annotated PlainDate strings (as produced by convertDateToCalendar) — E5 (issue #78). When both date1 and date2 carry the same calendar tag, the difference is measured in that calendar (a Hebrew leap year is P12M12D, not P1Y, in month/day units — see the roadmap’s E5 decisions of record, D5). When they carry different tags (or either is a bare, untagged ISO string), the difference falls back to measuring in Gregorian. smallestUnit, roundingIncrement, and roundingMode control optional rounding of the result, per Temporal’s DifferenceOptions — e.g. &#123; smallestUnit: "week", roundingMode: "halfExpand" &#125; 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. ["month", "day"] with smallestUnit: "year") — this combination is rejected by Temporal and returns null, same as other invalid input.

Parameters

Section titled “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 any DateDurationUnit | DateDurationUnit[] to measure the difference
options RoundingOptions&lt;Temporal.DateUnit&gt; optional: smallestUnit, roundingIncrement, roundingMode (Temporal.DifferenceOptions rounding controls)

Returns

Section titled “Returns”

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

Section titled “Related types”

Examples

Section titled “Examples”
diffDate("2024-03-10", "2024-03-15", "day") // 5
diffDate("invalid", "2024-03-15", "day") // null
diffDate("2024-01-01", "2024-01-16", "week", { smallestUnit: "week", roundingMode: "halfExpand" }) // 2
diffDate("5784-06-15[u-ca=hebrew]", "5784-07-15[u-ca=hebrew]", "months") // 1 (measured in Hebrew, Adar I -> Adar)

Source

Section titled “Source”

plain/calculate/diffDate.ts