areDateTimesEqualBy

Signature

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

Compare two ISO datetime strings for equality at a given 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.
• Comparison: date-fns’s isSameMonth and Luxon’s dt.hasSame(other, "month") give the same answer.
• Supports the full Temporal.DateUnit | Temporal.TimeUnit range, down to "nanosecond".
• 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) → areDateTimesEqualBy(a, b, "day")
• isSameHour(a, b) → areDateTimesEqualBy(a, b, "hour")
• isSameMinute(a, b) → areDateTimesEqualBy(a, b, "minute")
• isSameSecond(a, b) → areDateTimesEqualBy(a, b, "second")
• isSameMonth(a, b) → areDateTimesEqualBy(a, b, "month")
• isSameYear(a, b) → areDateTimesEqualBy(a, b, "year")

Parameters

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

Options

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.

Returns

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

Examples

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

areDateTimesEqualBy("2024-03-15T10:00:00", "2024-03-15T18:00:00", "day") // true

value1value2

output

 

Source

plain/compare/areDateTimesEqualBy.ts