isThisUnit

Signature

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

Return true when value falls in the same unit as today, per the system clock and system timeZone.

Subsumes isThisWeek/isThisMonth/isThisYear: unit is drawn from the same Temporal.DateUnit areDatesEqualBy uses.
"day" is equivalent to isRelativeDay(value, 0).
locale only affects the "week" case — which day the week starts on varies by locale (e.g. en-US: Sunday, fr-FR: Monday). When unit is "week" and locale is given, the comparison uses getLocaleStartOfWeek instead of the ISO Monday-start default areDatesEqualBy otherwise uses.
Compares against getToday(), so this depends on the system clock and system timeZone. A caller needing determinism should use isZonedThisUnit with an explicit timeZone, or compare against an explicit reference with areDatesEqualBy.
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". Mapping from date-fns:
isThisWeek(value, options) → isThisUnit(value, "week", locale)
isThisMonth(value) → isThisUnit(value, "month")
isThisYear(value) → isThisUnit(value, "year")

Parameter	Type	Description
`value`	`string`	ISO PlainDate 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”])

true if value falls in the same unit as today, false on an unsupported unit or invalid input

import { isThisUnit } from "@northguild/gmt/plain/compare";

isThisUnit("2024-03-15", "month") // true, if today is any day in March 2024