@burglekitt/gmt/dist/plain/compare/areDatesEqualBy.d.ts

Temporal-based date and time utilities with timezone support and polyfill integration

import { Temporal } from "@js-temporal/polyfill";
/**
 * 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")`
 *
 * @param value1 first ISO date string
 * @param value2 second ISO date string
 * @param unit Temporal.DateUnit to compare by ("year" | "month" | "week" | "day")
 * @param optionsArg optional: weekStartsOn ("monday" | "sunday")
 * @returns true if both dates share the same start-of-unit boundary, false on an unsupported unit or invalid input
 *
 * @example areDatesEqualBy("2024-03-15", "2024-03-20", "month") // true
 * @example areDatesEqualBy("2023-03-15", "2024-03-15", "month") // false (same month, different year)
 * @example areDatesEqualBy("2024-03-15", "2024-03-16", "day") // false
 * @example areDatesEqualBy("2024-03-15", "2024-03-15", "hour" as never) // false (unsupported unit)
 * @example areDatesEqualBy("invalid", "2024-03-15", "month") // false
 */
export declare function areDatesEqualBy(value1: string, value2: string, unit: Temporal.DateUnit, optionsArg?: {
    weekStartsOn?: "monday" | "sunday";
}): boolean;