areDatesEqualBy

Signature

areDatesEqualBy(value1: string, value2: string, unit: Temporal.DateUnit, optionsArg?: { weekStartsOn?: "monday" | "sunday"; }): boolean

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

Compare two ISO date strings for equality at a given calendar unit.

• Equality means both values share the same start-of-unit boundary, so "month" requires the same month AND year — March 2023 and March 2024 are NOT equal by month, matching date-fns’s isSameMonth and Luxon’s dt.hasSame(other, "month"). This is a common point of confusion for callers expecting a bare “same month-of-year” comparison.
• "day" is equivalent to areDatesEqual.
• "year", "month", "week" are computed via startOfDate.
• Returns false for an unsupported unit or invalid input. Mapping from date-fns (Decision 5, context/roadmap/issues/J.md):
• isSameDay(a, b) → areDatesEqualBy(a, b, "day")
• isSameWeek(a, b, options) → areDatesEqualBy(a, b, "week", { weekStartsOn })
• isSameMonth(a, b) → areDatesEqualBy(a, b, "month")
• isSameYear(a, b) → areDatesEqualBy(a, b, "year")

Parameters

Parameter	Type	Description
value1	string	first ISO date string
value2	string	second ISO date string
unit	Temporal.DateUnit	Temporal.DateUnit to compare by (“year” | “month” | “week” | “day”)

Options

options

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

Returns

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

Related types

• DateUnit

Examples

areDatesEqualBy("2024-03-15", "2024-03-20", "month") // true
areDatesEqualBy("2023-03-15", "2024-03-15", "month") // false (same month, different year)
areDatesEqualBy("2024-03-15", "2024-03-16", "day") // false
areDatesEqualBy("2024-03-15", "2024-03-15", "hour" as never) // false (unsupported unit)
areDatesEqualBy("invalid", "2024-03-15", "month") // false

Source

plain/compare/areDatesEqualBy.ts