areDatesEqualBy

Signature

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

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. A calendar month is a year and a month together, as in Temporal’s PlainYearMonth, not a bare month-of-year number. This is a common point of confusion for callers expecting a bare “same month-of-year” comparison.
Comparison: date-fns’s isSameMonth and Luxon’s dt.hasSame(other, "month") give the same answer.
"day" matches areDatesEqual for PlainDate inputs only: areDatesEqual also accepts PlainDateTime strings (areDatesEqual("2024-01-01", "2024-01-01T10:00") is true), while this function accepts PlainDate strings only (areDatesEqualBy with those inputs and "day" is false).
"year", "month", "week" are computed via startOfDate.
unit accepts 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) → 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")

Parameter	Type	Description
`value1`	`string`	first ISO date string
`value2`	`string`	second ISO date string
`unit`	`SmallestUnit<DateUnit>`	date unit to compare by (“year” \| “month” \| “week” \| “day”, or its plural)

optionsArg

How the week is defined

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 dates share the same start-of-unit boundary, false on an unsupported unit or invalid input

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

areDatesEqualBy("2024-03-15", "2024-03-20", "month") // true