closestDateTo

Signature

closestDateTo(target: string, candidates: string[]): string

Return the candidate date nearest to target by calendar distance.

• Distance is the absolute whole-day count Math.abs(target.until(candidate).days). Temporal.PlainDate.compare is not used for it: compare orders two dates (-1, 0, 1), it does not measure between them. until() on a PlainDate defaults to largestUnit: "day", so the count runs across month and year boundaries — 2024-03-15 to 2026-01-01 is 657.
• Returns "" if the candidates array is empty or contains no valid dates, or target is invalid.
• Compatibility: before 1.16.0 invalid input returned null.
• On a tie (two equidistant candidates), returns the first one in array order.

Parameters

Parameter	Type	Description
target	string	ISO PlainDate string to measure distance from
candidates	string[]	Array of ISO PlainDate strings to choose from

Returns

The nearest candidate date string, or "" on invalid input

Examples

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

closestDateTo("2024-03-15", ["2024-03-01", "2024-03-20", "2024-03-18"]) // "2024-03-18"

target

candidates

×

×

×

+ add

output

 

Source

plain/calculate/closestDateTo.ts