isZonedThisUnit

Signature

isZonedThisUnit(value: string, unit: SmallestUnit<DateUnit>, locale?: string | string[]): boolean

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.
• unit accepts the singular or plural name ("month" or "months"), as Temporal does.
• locale may be a BCP 47 tag or a preference list of tags (ECMA-402); the first tag with locale data sets the week start.
• Returns false for an unsupported unit or invalid input. The locale is validated for every unit, so an invalid locale returns false for "day", "month" and "year" too.
• Compatibility: before 1.16.0 an invalid locale was ignored for every unit but "week".

Parameters

Parameter	Type	Description
value	string	ISO ZonedDateTime string
unit	SmallestUnit<DateUnit>	date unit to compare by (“year” | “month” | “week” | “day”, or its plural)
locale	string | string[]	optional BCP 47 locale tag or preference list — sets the “week” start (e.g. “en-US”, [“fr-FR”, “en-US”])

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

Examples

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

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

valuelocale ?

output

 

Source

zoned/compare/isZonedThisUnit.ts