closestZonedTo

Signature

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

import { closestZonedTo } from "@northguild/gmt/zoned/calculate";

Return the candidate zoned datetime nearest to target by temporal distance.

• Distance is measured in total days using Temporal.Instant epoch milliseconds.
• Returns null if the candidates array is empty or contains no valid dates.
• Returns null if target is invalid.
• On a tie (two equidistant candidates), returns the first one in array order.

Parameters

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

Returns

The nearest candidate zoned datetime string, or null on invalid input

Examples

closestZonedTo("2024-03-15T12:00:00+00:00[UTC]", ["2024-03-01T00:00:00+00:00[UTC]", "2024-03-20T00:00:00+00:00[UTC]", "2024-03-18T00:00:00+00:00[UTC]"]) // "2024-03-18T00:00:00+00:00[UTC]"
closestZonedTo("2024-03-15T12:00:00+00:00[UTC]", ["2024-03-01T00:00:00+00:00[UTC]", "2024-03-29T00:00:00+00:00[UTC]"]) // "2024-03-29T00:00:00+00:00[UTC]"
closestZonedTo("2024-03-15T12:00:00+00:00[UTC]", []) // null
closestZonedTo("invalid", ["2024-03-01T00:00:00+00:00[UTC]"]) // null

Source

zoned/calculate/closestZonedTo.ts