areZonedEqualBy
Signature
Section titled “Signature”areZonedEqualBy(value1: string, value2: string, unit: SmallestUnit<DateTimeUnit>, optionsArg?: { weekStartsOn?: "monday" | "sunday"; }): booleanCompare two zoned ISO datetime strings for equality at a given unit.
- Equality is measured on each value’s own local wall-clock fields (its own time zone), not on the underlying instant or time zone identifier — the same instant can be “the same day” in one zone and a different day in another, and this function answers per each value’s own zone, because a
Temporal.ZonedDateTimereads its calendar and clock fields in its own time zone. - Comparison: Luxon’s
dt.hasSame(other, unit)also compares the two values’ local times. - Each value’s start-of-unit is its real local bucket (see
startOfZoned), so a bucket a zone transition shortened is still its own unit: inPacific/Chathamon its 2024 spring-forward, 03:50 and 04:05 are different hours, because the 03:00 hour lasted only from 03:45 to 04:00. - Two values in the same time zone are equal only when their bucket starts are the same instant, as in
areUnixEqualBy: both passes of New York’s repeated 01:00 on its 2024 fall-back read the same wall clock but are different hours. Values in different zones are compared by their buckets’ local labels, since their instants never line up. "month"requires the same month AND year, matchingareDateTimesEqualBy.unitaccepts the singular or plural name ("day"or"days"), as Temporal does.- Returns false for an unsupported unit or invalid input. Mapping from date-fns:
isSameDay(a, b)→areZonedEqualBy(a, b, "day")isSameMonth(a, b)→areZonedEqualBy(a, b, "month")isSameYear(a, b)→areZonedEqualBy(a, b, "year")
Parameters
Section titled “Parameters”| Parameter | Type | Description |
|---|---|---|
value1 | string | first zoned ISO datetime string |
value2 | string | second zoned ISO datetime string |
unit | SmallestUnit<DateTimeUnit> | date or time unit, singular or plural, to compare by |
Options
Section titled “Options”optionsArg
optional setting for the week’s first day
| Option | Type | Default | Description |
|---|---|---|---|
weekStartsOn? | "monday" | "sunday" | "monday" | The first day of the week, which sets where a "week" unit starts. "monday" is the ISO 8601 week, Monday to Sunday; "sunday" runs Sunday to Saturday. Any other value returns false, whatever the unit. |
Returns
Section titled “Returns”true if both values share the same local start-of-unit boundary, false on an unsupported unit or invalid input
Related types
Section titled “Related types”Examples
Section titled “Examples”import { areZonedEqualBy } from "@northguild/gmt/zoned/compare";
areZonedEqualBy("2024-03-15T10:00:00-04:00[America/New_York]", "2024-03-15T20:00:00+01:00[Europe/Berlin]", "day") // true (both are local March 15 in their own zone)