areUtcEqualBy

Signature

areUtcEqualBy(value1: string, value2: string, unit: SmallestUnit<DateTimeUnit>, options?: { weekStartsOn?: "monday" | "sunday"; }): boolean

Compare two UTC ISO datetime strings for equality at a given unit.

Both values are resolved to the start of unit in UTC before comparison, so "day" always means the UTC calendar day (UTC has no DST, so this is unambiguous).
"month" requires the same month AND year, matching areDateTimesEqualBy.
unit accepts the singular or plural name ("day" or "days"), as Temporal does.
Returns false for an unsupported unit or invalid input.
Takes no fractionalSecondDigits: equality compares full-precision unit boundaries, and output digits cannot change which bucket a value is in. That ignored option was removed in 1.16.0; to compare more coarsely, pass a coarser unit (0 digits is "second", 3 is "millisecond"). Mapping from date-fns:
isSameDay(a, b) → areUtcEqualBy(a, b, "day")
isSameMonth(a, b) → areUtcEqualBy(a, b, "month")
isSameYear(a, b) → areUtcEqualBy(a, b, "year")

Parameter	Type	Description
`value1`	`string`	first UTC ISO datetime string
`value2`	`string`	second UTC ISO datetime string
`unit`	`SmallestUnit<DateTimeUnit>`	date or time unit, singular or plural, to compare by

options

Where a week starts

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.

true if both values share the same start-of-unit boundary, false on an unsupported unit or invalid input

import { areUtcEqualBy } from "@northguild/gmt/utc/compare";

areUtcEqualBy("2024-03-15T02:00:00Z", "2024-03-15T22:00:00Z", "day") // true