areUtcEqualBy

Signature

areUtcEqualBy(value1: string, value2: string, unit: any, options?: { weekStartsOn?: "monday" | "sunday"; fractionalSecondDigits?: FractionalDigit; }): boolean

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

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.
• Returns false for an unsupported unit or invalid input. Mapping from date-fns (Decision 5, context/roadmap/issues/J.md):
• isSameDay(a, b) → areUtcEqualBy(a, b, "day")
• isSameMonth(a, b) → areUtcEqualBy(a, b, "month")
• isSameYear(a, b) → areUtcEqualBy(a, b, "year")

Parameters

Parameter	Type	Description
value1	string	first UTC ISO datetime string
value2	string	second UTC ISO datetime string
unit	any	Temporal.DateUnit | Temporal.TimeUnit to compare by

Options

options

Option	Type	Default
weekStartsOn?	"monday" | "sunday"	—
fractionalSecondDigits?	FractionalDigit	—

Returns

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

Related types

• FractionalDigit

Examples

areUtcEqualBy("2024-03-15T02:00:00Z", "2024-03-15T22:00:00Z", "day") // true
areUtcEqualBy("2024-03-15T23:30:00Z", "2024-03-16T00:30:00Z", "day") // false
areUtcEqualBy("invalid", "2024-03-15T02:00:00Z", "day") // false

Source

utc/compare/areUtcEqualBy.ts