isZonedThisUnit

Signature

isZonedThisUnit(value: string, unit: Temporal.DateUnit, locale?: string): boolean

import { isZonedThisUnit } from "@northguild/gmt/zoned/compare";

Return true when value’s local calendar day falls in the same unit as

• today, both resolved in value’s own IANA timeZone.
• Subsumes isZonedThisWeek/isZonedThisMonth/isZonedThisYear; unit is drawn from the same Temporal.DateUnit isThisUnit uses.
• “Today” is resolved in value’s own timeZone — no separate timeZone argument needed, since value already carries its IANA timeZone. This is the deterministic counterpart to isThisUnit, which depends on the system clock and system timeZone.
• locale only affects the "week" case — which day the week starts on varies by locale. When unit is "week" and locale is given, the comparison uses getLocaleStartOfWeek instead of the ISO Monday-start default areDatesEqualBy otherwise uses.
• Returns false for an unsupported unit, invalid input, or an invalid locale.

Parameters

Parameter	Type	Description
value	string	ISO ZonedDateTime string
unit	Temporal.DateUnit	Temporal.DateUnit to compare by (“year” | “month” | “week” | “day”)
locale	string	optional BCP 47 locale tag — only affects the “week” case (e.g. “en-US”, “fr-FR”)

Returns

true if value’s local day falls in the same unit as today in its own timeZone, false on an unsupported unit or invalid input

Related types

• DateUnit

Examples

isZonedThisUnit("2024-03-15T10:00:00-04:00[America/New_York]", "month") // true, if today is any day in March 2024 in America/New_York
isZonedThisUnit("2024-02-26T10:00:00+01:00[Europe/Paris]", "week", "fr-FR") // true, if today is 2024-03-01 in Europe/Paris (same fr-FR Monday-start week)
isZonedThisUnit("2024-03-15T10:00:00-04:00[America/New_York]", "hour" as never) // false (unsupported unit)
isZonedThisUnit("invalid", "month") // false

Source

zoned/compare/isZonedThisUnit.ts