@northguild/gmt 1.14.2

package/dist/plain/calculate/subtractDate.js

@@ -0,0 +1,47 @@
+import { calendarSystemOfDateValue, formatDateInCalendar, isValidAmount, parseCalendarDateValue, resolveOverflow, } from "../../internal/index.js";
+import { isValidCalendarDate, isValidDateDurationUnit } from "../validate/index.js";
+/**
+ * Return a PlainDate ISO string with `units` subtracted from `value`.
+ *
+ * - Validates `value`, `units`, and `amount` before performing the subtract.
+ * - Accepts a GMT calendar-annotated PlainDate string (as produced by `convertDateToCalendar`),
+ *   not just a bare ISO string — E5 (issue #78). See `addDate`'s JSDoc for the full calendar-unit
+ *   arithmetic rationale (leap months/years, era transitions, the `overflow` asymmetry); this
+ *   function is the mirror image (`.subtract` instead of `.add`).
+ * - Returns "" for invalid inputs.
+ *
+ * `overflow` ("constrain" (default) | "reject") controls out-of-range results, e.g. subtracting
+ * 1 month from Mar 31: "constrain" clamps to Feb 29/28, "reject" throws (resulting in "").
+ *
+ * @param value ISO PlainDate string, optionally calendar-annotated
+ * @param units Partial<Record<DateDurationUnit, number>> object specifying units to subtract
+ * @param options optional: overflow ("constrain" | "reject")
+ * @returns ISO PlainDate string after subtraction, or "" on invalid input
+ *
+ * @example subtractDate("2024-03-15", { day: 5 }) // "2024-03-10"
+ * @example subtractDate("invalid", { day: 5 }) // ""
+ * @example subtractDate("2024-03-31", { months: 1 }, { overflow: "reject" }) // ""
+ * @example subtractDate("5784-07-15[u-ca=hebrew]", { months: 1 }) // "5784-06-15[u-ca=hebrew]" (Adar -> Adar I)
+ */
+export function subtractDate(value, units, options) {
+    const validDate = isValidCalendarDate(value);
+    const validUnits = Object.keys(units).every(isValidDateDurationUnit);
+    const validAmounts = Object.values(units).every(isValidAmount);
+    if (!validDate || !validUnits || !validAmounts) {
+        return "";
+    }
+    try {
+        const calendar = calendarSystemOfDateValue(value);
+        if (!calendar) {
+            return "";
+        }
+        const date = parseCalendarDateValue(value);
+        const result = date.subtract(units, {
+            overflow: resolveOverflow(options?.overflow),
+        });
+        return formatDateInCalendar(result, calendar);
+    }
+    catch {
+        return "";
+    }
+}

package/dist/plain/calculate/subtractDateTime.d.ts

@@ -0,0 +1,22 @@
+import type { DateTimeDurationUnit, Overflow } from "../../types/index.js";
+/**
+ * Return a PlainDateTime ISO string with `units` subtracted from `value`.
+ *
+ * - Validates `value`, `units`, and `amount` before performing the subtract.
+ * - Returns "" for invalid inputs.
+ *
+ * `overflow` ("constrain" (default) | "reject") controls out-of-range results, e.g. subtracting
+ * 1 month from Mar 31: "constrain" clamps to Feb 29/28, "reject" throws (resulting in "").
+ *
+ * @param value ISO PlainDateTime string
+ * @param units Partial<Record<DateTimeDurationUnit, number>> object specifying units to subtract
+ * @param options optional: overflow ("constrain" | "reject")
+ * @returns ISO PlainDateTime string after subtraction, or "" on invalid input
+ *
+ * @example subtractDateTime("2024-03-15T12:00:00", { days: 5 }) // "2024-03-10T12:00:00"
+ * @example subtractDateTime("invalid", { days: 5 }) // ""
+ * @example subtractDateTime("2024-03-31T12:00:00", { months: 1 }, { overflow: "reject" }) // ""
+ */
+export declare function subtractDateTime(value: string, units: Partial<Record<DateTimeDurationUnit, number>>, options?: {
+    overflow?: Overflow;
+}): string;

package/dist/plain/calculate/subtractDateTime.js

@@ -0,0 +1,38 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidAmount, resolveOverflow } from "../../internal/index.js";
+import { isValidDateTime, isValidDateTimeDurationUnit } from "../validate/index.js";
+/**
+ * Return a PlainDateTime ISO string with `units` subtracted from `value`.
+ *
+ * - Validates `value`, `units`, and `amount` before performing the subtract.
+ * - Returns "" for invalid inputs.
+ *
+ * `overflow` ("constrain" (default) | "reject") controls out-of-range results, e.g. subtracting
+ * 1 month from Mar 31: "constrain" clamps to Feb 29/28, "reject" throws (resulting in "").
+ *
+ * @param value ISO PlainDateTime string
+ * @param units Partial<Record<DateTimeDurationUnit, number>> object specifying units to subtract
+ * @param options optional: overflow ("constrain" | "reject")
+ * @returns ISO PlainDateTime string after subtraction, or "" on invalid input
+ *
+ * @example subtractDateTime("2024-03-15T12:00:00", { days: 5 }) // "2024-03-10T12:00:00"
+ * @example subtractDateTime("invalid", { days: 5 }) // ""
+ * @example subtractDateTime("2024-03-31T12:00:00", { months: 1 }, { overflow: "reject" }) // ""
+ */
+export function subtractDateTime(value, units, options) {
+    const validDateTime = isValidDateTime(value);
+    const validUnits = Object.keys(units).every(isValidDateTimeDurationUnit);
+    const validAmounts = Object.values(units).every(isValidAmount);
+    if (!validDateTime || !validUnits || !validAmounts) {
+        return "";
+    }
+    try {
+        const dateTime = Temporal.PlainDateTime.from(value);
+        return dateTime
+            .subtract(units, { overflow: resolveOverflow(options?.overflow) })
+            .toString();
+    }
+    catch {
+        return "";
+    }
+}

package/dist/plain/calculate/subtractTime.d.ts

@@ -0,0 +1,22 @@
+import type { Overflow, TimeDurationUnit } from "../../types/index.js";
+/**
+ * Return a PlainTime ISO string with `units` subtracted from `value`.
+ *
+ * - Validates `value`, `units`, and `amount` before performing the subtract.
+ * - Returns "" for invalid inputs.
+ *
+ * `overflow` ("constrain" (default) | "reject") is accepted for API consistency with sibling
+ * subtract functions, but PlainTime arithmetic always wraps around the clock (e.g. 01:00 - 2 hours
+ * = 23:00) rather than producing an out-of-range value, so it has no observable effect here.
+ *
+ * @param value ISO PlainTime string
+ * @param units Partial<Record<TimeDurationUnit, number>> object specifying units to subtract
+ * @param options optional: overflow ("constrain" | "reject" — accepted but inert, see above)
+ * @returns ISO PlainTime string after subtraction, or "" on invalid input
+ *
+ * @example subtractTime("14:30:00", { hours: 1 }) // "13:30:00"
+ * @example subtractTime("invalid", { hours: 1 }) // ""
+ */
+export declare function subtractTime(value: string, units: Partial<Record<TimeDurationUnit, number>>, options?: {
+    overflow?: Overflow;
+}): string;

package/dist/plain/calculate/subtractTime.js

@@ -0,0 +1,38 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidAmount, resolveOverflow } from "../../internal/index.js";
+import { isValidTime, isValidTimeDurationUnit } from "../validate/index.js";
+/**
+ * Return a PlainTime ISO string with `units` subtracted from `value`.
+ *
+ * - Validates `value`, `units`, and `amount` before performing the subtract.
+ * - Returns "" for invalid inputs.
+ *
+ * `overflow` ("constrain" (default) | "reject") is accepted for API consistency with sibling
+ * subtract functions, but PlainTime arithmetic always wraps around the clock (e.g. 01:00 - 2 hours
+ * = 23:00) rather than producing an out-of-range value, so it has no observable effect here.
+ *
+ * @param value ISO PlainTime string
+ * @param units Partial<Record<TimeDurationUnit, number>> object specifying units to subtract
+ * @param options optional: overflow ("constrain" | "reject" — accepted but inert, see above)
+ * @returns ISO PlainTime string after subtraction, or "" on invalid input
+ *
+ * @example subtractTime("14:30:00", { hours: 1 }) // "13:30:00"
+ * @example subtractTime("invalid", { hours: 1 }) // ""
+ */
+export function subtractTime(value, units, options) {
+    const validTime = isValidTime(value);
+    const validUnits = Object.keys(units).every(isValidTimeDurationUnit);
+    const validAmounts = Object.values(units).every(isValidAmount);
+    if (!validTime || !validUnits || !validAmounts) {
+        return "";
+    }
+    try {
+        const time = Temporal.PlainTime.from(value);
+        return time
+            .subtract(units, { overflow: resolveOverflow(options?.overflow) })
+            .toString();
+    }
+    catch {
+        return "";
+    }
+}

package/dist/plain/calculate/weekOfYear.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Return the ISO week number for a given ISO 8601 date string.
+ *
+ * - Uses Temporal.PlainDate.weekOfYear (Monday-based ISO weeks).
+ * - Returns null for invalid input.
+ *
+ * @param value ISO 8601 date string
+ * @returns Week number (1-53) or null on invalid input
+ *
+ * @example weekOfYearForDate("2024-01-01") // 1
+ * @example weekOfYearForDate("2024-01-07") // 1
+ * @example weekOfYearForDate("2024-01-08") // 2
+ * @example weekOfYearForDate("2024-12-31") // 1
+ * @example weekOfYearForDate("invalid") // null
+ */
+export declare function weekOfYearForDate(value: string): number | null;
+/**
+ * Return the ISO week number for a given ISO 8601 datetime string.
+ *
+ * - Uses Temporal.PlainDate.weekOfYear (Monday-based ISO weeks).
+ * - Returns null for invalid input.
+ *
+ * @param value ISO 8601 datetime string
+ * @returns Week number (1-53) or null on invalid input
+ *
+ * @example weekOfYearForDateTime("2024-01-01T12:00:00") // 1
+ * @example weekOfYearForDateTime("2024-01-08T00:00:00") // 2
+ * @example weekOfYearForDateTime("invalid") // null
+ */
+export declare function weekOfYearForDateTime(value: string): number | null;

package/dist/plain/calculate/weekOfYear.js

@@ -0,0 +1,57 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidDate, isValidDateTime } from "../validate/index.js";
+/**
+ * Return the ISO week number for a given ISO 8601 date string.
+ *
+ * - Uses Temporal.PlainDate.weekOfYear (Monday-based ISO weeks).
+ * - Returns null for invalid input.
+ *
+ * @param value ISO 8601 date string
+ * @returns Week number (1-53) or null on invalid input
+ *
+ * @example weekOfYearForDate("2024-01-01") // 1
+ * @example weekOfYearForDate("2024-01-07") // 1
+ * @example weekOfYearForDate("2024-01-08") // 2
+ * @example weekOfYearForDate("2024-12-31") // 1
+ * @example weekOfYearForDate("invalid") // null
+ */
+export function weekOfYearForDate(value) {
+    if (!isValidDate(value))
+        return null;
+    try {
+        const date = Temporal.PlainDate.from(value);
+        return date.weekOfYear ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Return the ISO week number for a given ISO 8601 datetime string.
+ *
+ * - Uses Temporal.PlainDate.weekOfYear (Monday-based ISO weeks).
+ * - Returns null for invalid input.
+ *
+ * @param value ISO 8601 datetime string
+ * @returns Week number (1-53) or null on invalid input
+ *
+ * @example weekOfYearForDateTime("2024-01-01T12:00:00") // 1
+ * @example weekOfYearForDateTime("2024-01-08T00:00:00") // 2
+ * @example weekOfYearForDateTime("invalid") // null
+ */
+export function weekOfYearForDateTime(value) {
+    if (!isValidDateTime(value))
+        return null;
+    try {
+        const dateTime = Temporal.PlainDateTime.from(value);
+        const date = Temporal.PlainDate.from({
+            year: dateTime.year,
+            month: dateTime.month,
+            day: dateTime.day,
+        });
+        return date.weekOfYear ?? null;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/plain/chop/chopDate.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Return the PlainTime portion extracted from an ISO PlainDateTime string.
+ *
+ * - Extracts time components from a PlainDateTime.
+ * - Returns "" for invalid input.
+ *
+ * @param value ISO PlainDateTime string
+ * @returns ISO PlainTime string or "" on invalid input
+ *
+ * @example chopDate("2024-02-29T12:34:56") // "12:34:56"
+ * @example chopDate("invalid") // ""
+ */
+export declare function chopDate(value: string): string;

package/dist/plain/chop/chopDate.js

@@ -0,0 +1,24 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidDateTime } from "../validate/index.js";
+/**
+ * Return the PlainTime portion extracted from an ISO PlainDateTime string.
+ *
+ * - Extracts time components from a PlainDateTime.
+ * - Returns "" for invalid input.
+ *
+ * @param value ISO PlainDateTime string
+ * @returns ISO PlainTime string or "" on invalid input
+ *
+ * @example chopDate("2024-02-29T12:34:56") // "12:34:56"
+ * @example chopDate("invalid") // ""
+ */
+export function chopDate(value) {
+    if (!isValidDateTime(value))
+        return "";
+    try {
+        return Temporal.PlainDateTime.from(value).toPlainTime().toString();
+    }
+    catch {
+        return "";
+    }
+}

package/dist/plain/chop/chopMilliseconds.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Return a string with millisecond precision removed from a PlainDateTime or PlainTime value.
+ *
+ * - Truncates to second precision.
+ * - Accepts both PlainDateTime and PlainTime formats.
+ * - Returns "" for invalid input.
+ *
+ * @param value ISO PlainDateTime or PlainTime string
+ * @returns ISO string without milliseconds, or "" on invalid input
+ *
+ * @example chopMilliseconds("2024-02-29T12:34:56.789") // "2024-02-29T12:34:56"
+ * @example chopMilliseconds("12:34:56.789") // "12:34:56"
+ * @example chopMilliseconds("invalid") // ""
+ */
+export declare function chopMilliseconds(value: string): string;

package/dist/plain/chop/chopMilliseconds.js

@@ -0,0 +1,34 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidDateTime, isValidTime } from "../validate/index.js";
+/**
+ * Return a string with millisecond precision removed from a PlainDateTime or PlainTime value.
+ *
+ * - Truncates to second precision.
+ * - Accepts both PlainDateTime and PlainTime formats.
+ * - Returns "" for invalid input.
+ *
+ * @param value ISO PlainDateTime or PlainTime string
+ * @returns ISO string without milliseconds, or "" on invalid input
+ *
+ * @example chopMilliseconds("2024-02-29T12:34:56.789") // "2024-02-29T12:34:56"
+ * @example chopMilliseconds("12:34:56.789") // "12:34:56"
+ * @example chopMilliseconds("invalid") // ""
+ */
+export function chopMilliseconds(value) {
+    try {
+        if (isValidDateTime(value)) {
+            return Temporal.PlainDateTime.from(value).toString({
+                smallestUnit: "second",
+            });
+        }
+        if (isValidTime(value)) {
+            return Temporal.PlainTime.from(value).toString({
+                smallestUnit: "second",
+            });
+        }
+        return "";
+    }
+    catch {
+        return "";
+    }
+}

package/dist/plain/chop/chopSeconds.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Return an ISO string with second precision removed from a PlainDateTime or PlainTime value.
+ *
+ * - Truncates to minute precision.
+ * - Accepts both PlainDateTime and PlainTime formats.
+ * - Returns "" for invalid input.
+ *
+ * @param value ISO PlainDateTime or PlainTime string
+ * @returns ISO string trimmed to minutes or "" on invalid input
+ *
+ * @example chopSeconds("2024-02-29T12:34:56") // "2024-02-29T12:34"
+ * @example chopSeconds("12:34:56") // "12:34"
+ * @example chopSeconds("invalid") // ""
+ */
+export declare function chopSeconds(value: string): string;

package/dist/plain/chop/chopSeconds.js

@@ -0,0 +1,34 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidDateTime, isValidTime } from "../validate/index.js";
+/**
+ * Return an ISO string with second precision removed from a PlainDateTime or PlainTime value.
+ *
+ * - Truncates to minute precision.
+ * - Accepts both PlainDateTime and PlainTime formats.
+ * - Returns "" for invalid input.
+ *
+ * @param value ISO PlainDateTime or PlainTime string
+ * @returns ISO string trimmed to minutes or "" on invalid input
+ *
+ * @example chopSeconds("2024-02-29T12:34:56") // "2024-02-29T12:34"
+ * @example chopSeconds("12:34:56") // "12:34"
+ * @example chopSeconds("invalid") // ""
+ */
+export function chopSeconds(value) {
+    try {
+        if (isValidDateTime(value)) {
+            return Temporal.PlainDateTime.from(value).toString({
+                smallestUnit: "minute",
+            });
+        }
+        if (isValidTime(value)) {
+            return Temporal.PlainTime.from(value).toString({
+                smallestUnit: "minute",
+            });
+        }
+        return "";
+    }
+    catch {
+        return "";
+    }
+}

package/dist/plain/chop/chopTime.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Return the PlainDate portion extracted from an ISO PlainDateTime string.
+ *
+ * - Extracts date components from a PlainDateTime.
+ * - Returns "" for invalid input.
+ *
+ * @param value ISO PlainDateTime string
+ * @returns ISO PlainDate string or "" on invalid input
+ *
+ * @example chopTime("2024-02-29T12:34:56") // "2024-02-29"
+ * @example chopTime("invalid") // ""
+ */
+export declare function chopTime(value: string): string;

package/dist/plain/chop/chopTime.js

@@ -0,0 +1,24 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidDateTime } from "../validate/index.js";
+/**
+ * Return the PlainDate portion extracted from an ISO PlainDateTime string.
+ *
+ * - Extracts date components from a PlainDateTime.
+ * - Returns "" for invalid input.
+ *
+ * @param value ISO PlainDateTime string
+ * @returns ISO PlainDate string or "" on invalid input
+ *
+ * @example chopTime("2024-02-29T12:34:56") // "2024-02-29"
+ * @example chopTime("invalid") // ""
+ */
+export function chopTime(value) {
+    if (!isValidDateTime(value))
+        return "";
+    try {
+        return Temporal.PlainDateTime.from(value).toPlainDate().toString();
+    }
+    catch {
+        return "";
+    }
+}

package/dist/plain/chop/index.d.ts

@@ -0,0 +1,5 @@
+export * from "../../utc/chop/index.js";
+export * from "./chopDate.js";
+export * from "./chopMilliseconds.js";
+export * from "./chopSeconds.js";
+export * from "./chopTime.js";

package/dist/plain/chop/index.js

@@ -0,0 +1,5 @@
+export * from "../../utc/chop/index.js";
+export * from "./chopDate.js";
+export * from "./chopMilliseconds.js";
+export * from "./chopSeconds.js";
+export * from "./chopTime.js";

package/dist/plain/compare/areDateTimesEqual.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Return true if two PlainDateTime ISO strings represent the same instant of local date/time components.
+ *
+ * - Compares all date and time components.
+ * - Returns false if either input is invalid.
+ *
+ * @param value1 first ISO PlainDateTime string
+ * @param value2 second ISO PlainDateTime string
+ * @returns boolean indicating whether both date-times are equal component-wise
+ *
+ * @example areDateTimesEqual("2024-02-29T12:34:56", "2024-02-29T12:34:56") // true
+ * @example areDateTimesEqual("2024-02-29T12:34:56", "2024-02-29T12:34:57") // false
+ * @example areDateTimesEqual("2024-02-29T12:34:56", "invalid") // false
+ */
+export declare function areDateTimesEqual(value1: string, value2: string): boolean;

package/dist/plain/compare/areDateTimesEqual.js

@@ -0,0 +1,37 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidDateTime } from "../validate/index.js";
+/**
+ * Return true if two PlainDateTime ISO strings represent the same instant of local date/time components.
+ *
+ * - Compares all date and time components.
+ * - Returns false if either input is invalid.
+ *
+ * @param value1 first ISO PlainDateTime string
+ * @param value2 second ISO PlainDateTime string
+ * @returns boolean indicating whether both date-times are equal component-wise
+ *
+ * @example areDateTimesEqual("2024-02-29T12:34:56", "2024-02-29T12:34:56") // true
+ * @example areDateTimesEqual("2024-02-29T12:34:56", "2024-02-29T12:34:57") // false
+ * @example areDateTimesEqual("2024-02-29T12:34:56", "invalid") // false
+ */
+export function areDateTimesEqual(value1, value2) {
+    if (!isValidDateTime(value1) || !isValidDateTime(value2)) {
+        return false;
+    }
+    try {
+        const dateTime1 = Temporal.PlainDateTime.from(value1);
+        const dateTime2 = Temporal.PlainDateTime.from(value2);
+        return (dateTime1.year === dateTime2.year &&
+            dateTime1.month === dateTime2.month &&
+            dateTime1.day === dateTime2.day &&
+            dateTime1.hour === dateTime2.hour &&
+            dateTime1.minute === dateTime2.minute &&
+            dateTime1.second === dateTime2.second &&
+            dateTime1.millisecond === dateTime2.millisecond &&
+            dateTime1.microsecond === dateTime2.microsecond &&
+            dateTime1.nanosecond === dateTime2.nanosecond);
+    }
+    catch {
+        return false;
+    }
+}

package/dist/plain/compare/areDateTimesEqualBy.d.ts

@@ -0,0 +1,37 @@
+import { Temporal } from "@js-temporal/polyfill";
+import type { FractionalDigit } from "../../types/index.js";
+/**
+ * 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, matching date-fns's `isSameMonth` and Luxon's
+ *   `dt.hasSame(other, "month")`.
+ * - Supports the full `Temporal.DateUnit | Temporal.TimeUnit` range, down to
+ *   `"nanosecond"`.
+ * - Returns false for an unsupported unit or invalid input.
+ *
+ * Mapping from date-fns (Decision 5, `context/roadmap/issues/J.md`):
+ * - `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")`
+ *
+ * @param value1 first ISO datetime string
+ * @param value2 second ISO datetime string
+ * @param unit Temporal.DateUnit | Temporal.TimeUnit to compare by
+ * @param optionsArg optional: weekStartsOn ("monday" | "sunday"), fractionalSecondDigits (number)
+ * @returns true if both datetimes share the same start-of-unit boundary, false on an unsupported unit or invalid input
+ *
+ * @example areDateTimesEqualBy("2024-03-15T10:00:00", "2024-03-15T18:00:00", "day") // true
+ * @example areDateTimesEqualBy("2024-03-15T10:30:00", "2024-03-15T10:45:00", "hour") // true
+ * @example areDateTimesEqualBy("2024-03-15T10:30:00", "2024-03-15T11:00:00", "hour") // false
+ * @example areDateTimesEqualBy("2023-03-15T10:00:00", "2024-03-15T10:00:00", "month") // false (same month, different year)
+ * @example areDateTimesEqualBy("invalid", "2024-03-15T10:00:00", "day") // false
+ */
+export declare function areDateTimesEqualBy(value1: string, value2: string, unit: Temporal.DateUnit | Temporal.TimeUnit, optionsArg?: {
+    weekStartsOn?: "monday" | "sunday";
+    fractionalSecondDigits?: FractionalDigit;
+}): boolean;

package/dist/plain/compare/areDateTimesEqualBy.js

@@ -0,0 +1,49 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { startOfDateTime } from "../calculate/startOfDateTime.js";
+import { isValidDateTime, isValidDateTimeUnit } from "../validate/index.js";
+/**
+ * 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, matching date-fns's `isSameMonth` and Luxon's
+ *   `dt.hasSame(other, "month")`.
+ * - Supports the full `Temporal.DateUnit | Temporal.TimeUnit` range, down to
+ *   `"nanosecond"`.
+ * - Returns false for an unsupported unit or invalid input.
+ *
+ * Mapping from date-fns (Decision 5, `context/roadmap/issues/J.md`):
+ * - `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")`
+ *
+ * @param value1 first ISO datetime string
+ * @param value2 second ISO datetime string
+ * @param unit Temporal.DateUnit | Temporal.TimeUnit to compare by
+ * @param optionsArg optional: weekStartsOn ("monday" | "sunday"), fractionalSecondDigits (number)
+ * @returns true if both datetimes share the same start-of-unit boundary, false on an unsupported unit or invalid input
+ *
+ * @example areDateTimesEqualBy("2024-03-15T10:00:00", "2024-03-15T18:00:00", "day") // true
+ * @example areDateTimesEqualBy("2024-03-15T10:30:00", "2024-03-15T10:45:00", "hour") // true
+ * @example areDateTimesEqualBy("2024-03-15T10:30:00", "2024-03-15T11:00:00", "hour") // false
+ * @example areDateTimesEqualBy("2023-03-15T10:00:00", "2024-03-15T10:00:00", "month") // false (same month, different year)
+ * @example areDateTimesEqualBy("invalid", "2024-03-15T10:00:00", "day") // false
+ */
+export function areDateTimesEqualBy(value1, value2, unit, optionsArg) {
+    if (!isValidDateTime(value1) ||
+        !isValidDateTime(value2) ||
+        !isValidDateTimeUnit(unit)) {
+        return false;
+    }
+    try {
+        const start1 = startOfDateTime(value1, unit, optionsArg);
+        const start2 = startOfDateTime(value2, unit, optionsArg);
+        return start1 !== "" && start1 === start2;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/plain/compare/areDatesEqual.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Compare two ISO date-like strings for equality, ignoring time components.
+ *
+ * - Accepts both PlainDate and PlainDateTime strings.
+ * - Extracts date components only for comparison.
+ * - Returns false if either input is invalid.
+ *
+ * @param value1 ISO date-like string
+ * @param value2 ISO date-like string
+ * @returns true if the dates are equal, false otherwise
+ *
+ * @example areDatesEqual("2024-02-29", "2024-02-29T12:34:56") // true
+ * @example areDatesEqual("2024-02-29", "2024-03-01") // false
+ * @example areDatesEqual("invalid", "2024-02-29") // false
+ * @example areDatesEqual("2024-02-29", "invalid") // false
+ */
+export declare function areDatesEqual(value1: string, value2: string): boolean;

package/dist/plain/compare/areDatesEqual.js

@@ -0,0 +1,33 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidIsoDateLike } from "../validate/index.js";
+/**
+ * Compare two ISO date-like strings for equality, ignoring time components.
+ *
+ * - Accepts both PlainDate and PlainDateTime strings.
+ * - Extracts date components only for comparison.
+ * - Returns false if either input is invalid.
+ *
+ * @param value1 ISO date-like string
+ * @param value2 ISO date-like string
+ * @returns true if the dates are equal, false otherwise
+ *
+ * @example areDatesEqual("2024-02-29", "2024-02-29T12:34:56") // true
+ * @example areDatesEqual("2024-02-29", "2024-03-01") // false
+ * @example areDatesEqual("invalid", "2024-02-29") // false
+ * @example areDatesEqual("2024-02-29", "invalid") // false
+ */
+export function areDatesEqual(value1, value2) {
+    if (!isValidIsoDateLike(value1) || !isValidIsoDateLike(value2)) {
+        return false;
+    }
+    try {
+        const date1 = Temporal.PlainDate.from(value1);
+        const date2 = Temporal.PlainDate.from(value2);
+        return (date1.year === date2.year &&
+            date1.month === date2.month &&
+            date1.day === date2.day);
+    }
+    catch {
+        return false;
+    }
+}