@northguild/gmt 1.15.0 → 1.17.0

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

@@ -1,18 +1,33 @@
+import type { BusinessCalendar } from "../../types/index.js";
 /**
- * Return a PlainDate ISO string with `amount` business days subtracted from `value`.
+ * Return a PlainDate ISO string with `amount` working days subtracted from `value`.
  *
- * - Uses fixed ISO Monday–Friday business days (no locale awareness).
- * - Saturday and Sunday are skipped during the count.
- * - Negative `amount` behaves identically to `addBusinessDays(value, Math.abs(amount))`.
- * - Returns "" on invalid input.
+ * - `calendar` names the weekend days and holidays to skip. Omit it and GMT keeps its original
+ *   fixed Monday–Friday week with no holidays. Pass one anywhere the weekend is not
+ *   Saturday–Sunday — much of the Middle East is Friday–Saturday.
+ * - Negative `amount` behaves identically to `addBusinessDays(value, Math.abs(amount), cal)`.
+ * - `amount` of 0 returns `value` unchanged — including when `value` is not itself a working
+ *   day. Use `rollDate` to move a non-working day onto one.
+ * - `value` is never counted, so subtracting 1 from a holiday lands on the working day before
+ *   it.
+ * - `value` and `calendar.holidays` are local dates; `calendar.timeZone` is not read. A caller
+ *   holding an instant reduces it to a local date first, with `floorToZone`.
+ * - Returns "" on invalid input — including a fractional `amount`, which names no whole
+ *   number of working days — on an invalid `calendar`, and when the walk runs past
+ *   200,000 calendar days (about 547 years) without finishing.
  *
  * @param value ISO PlainDate string
- * @param amount number of business days to subtract
- * @returns ISO PlainDate string after subtracting business days, or "" on invalid input
+ * @param amount whole number of working days to subtract; negative walks forwards
+ * @param calendar optional BusinessCalendar; defaults to Monday–Friday with no holidays
+ * @returns ISO PlainDate string after subtracting working days, or "" on invalid input
  *
- * @example subtractBusinessDays("2024-03-18", 1) // "2024-03-15"
- * @example subtractBusinessDays("2024-03-17", 1) // "2024-03-15"
+ * @example subtractBusinessDays("2024-03-18", 1) // "2024-03-15" (Monday back to Friday)
+ * @example subtractBusinessDays("2024-03-17", 1) // "2024-03-15" (from a Sunday)
  * @example subtractBusinessDays("2024-03-18", 0) // "2024-03-18"
+ * @example subtractBusinessDays("2024-07-05", 1, { weekend: [6, 7], holidays: ["2024-07-04"], timeZone: "America/New_York" }) // "2024-07-03" (skips the holiday)
+ * @example subtractBusinessDays("2024-07-05", -1, { weekend: [6, 7], holidays: [], timeZone: "America/New_York" }) // "2024-07-08"
+ * @example subtractBusinessDays("2024-07-07", 1, { weekend: [5, 6], holidays: [], timeZone: "Asia/Riyadh" }) // "2024-07-04" (Friday–Saturday weekend)
  * @example subtractBusinessDays("invalid", 1) // ""
+ * @example subtractBusinessDays("2024-03-18", 1, { weekend: [6, 7], holidays: [], timeZone: "Invalid/Zone" }) // "" (bad calendar)
  */
-export declare function subtractBusinessDays(value: string, amount: number): string;
+export declare function subtractBusinessDays(value: string, amount: number, calendar?: BusinessCalendar): string;

package/dist/plain/calculate/subtractBusinessDays.js

@@ -1,36 +1,42 @@
-import { Temporal } from "@js-temporal/polyfill";
-import { advanceBusinessDays, isValidAmount } from "../../internal/index.js";
-import { isValidDate } from "../validate/index.js";
+import { stepBusinessDaysValue } from "../../internal/businessDayValues.js";
 /**
- * Return a PlainDate ISO string with `amount` business days subtracted from `value`.
+ * Return a PlainDate ISO string with `amount` working days subtracted from `value`.
  *
- * - Uses fixed ISO Monday–Friday business days (no locale awareness).
- * - Saturday and Sunday are skipped during the count.
- * - Negative `amount` behaves identically to `addBusinessDays(value, Math.abs(amount))`.
- * - Returns "" on invalid input.
+ * - `calendar` names the weekend days and holidays to skip. Omit it and GMT keeps its original
+ *   fixed Monday–Friday week with no holidays. Pass one anywhere the weekend is not
+ *   Saturday–Sunday — much of the Middle East is Friday–Saturday.
+ * - Negative `amount` behaves identically to `addBusinessDays(value, Math.abs(amount), cal)`.
+ * - `amount` of 0 returns `value` unchanged — including when `value` is not itself a working
+ *   day. Use `rollDate` to move a non-working day onto one.
+ * - `value` is never counted, so subtracting 1 from a holiday lands on the working day before
+ *   it.
+ * - `value` and `calendar.holidays` are local dates; `calendar.timeZone` is not read. A caller
+ *   holding an instant reduces it to a local date first, with `floorToZone`.
+ * - Returns "" on invalid input — including a fractional `amount`, which names no whole
+ *   number of working days — on an invalid `calendar`, and when the walk runs past
+ *   200,000 calendar days (about 547 years) without finishing.
  *
  * @param value ISO PlainDate string
- * @param amount number of business days to subtract
- * @returns ISO PlainDate string after subtracting business days, or "" on invalid input
+ * @param amount whole number of working days to subtract; negative walks forwards
+ * @param calendar optional BusinessCalendar; defaults to Monday–Friday with no holidays
+ * @returns ISO PlainDate string after subtracting working days, or "" on invalid input
  *
- * @example subtractBusinessDays("2024-03-18", 1) // "2024-03-15"
- * @example subtractBusinessDays("2024-03-17", 1) // "2024-03-15"
+ * @example subtractBusinessDays("2024-03-18", 1) // "2024-03-15" (Monday back to Friday)
+ * @example subtractBusinessDays("2024-03-17", 1) // "2024-03-15" (from a Sunday)
  * @example subtractBusinessDays("2024-03-18", 0) // "2024-03-18"
+ * @example subtractBusinessDays("2024-07-05", 1, { weekend: [6, 7], holidays: ["2024-07-04"], timeZone: "America/New_York" }) // "2024-07-03" (skips the holiday)
+ * @example subtractBusinessDays("2024-07-05", -1, { weekend: [6, 7], holidays: [], timeZone: "America/New_York" }) // "2024-07-08"
+ * @example subtractBusinessDays("2024-07-07", 1, { weekend: [5, 6], holidays: [], timeZone: "Asia/Riyadh" }) // "2024-07-04" (Friday–Saturday weekend)
  * @example subtractBusinessDays("invalid", 1) // ""
+ * @example subtractBusinessDays("2024-03-18", 1, { weekend: [6, 7], holidays: [], timeZone: "Invalid/Zone" }) // "" (bad calendar)
  */
-export function subtractBusinessDays(value, amount) {
-    if (!isValidDate(value) || !isValidAmount(amount)) {
-        return "";
-    }
-    if (amount === 0) {
-        return value;
-    }
+export function subtractBusinessDays(value, amount, calendar) {
     try {
-        const date = Temporal.PlainDate.from(value);
-        const direction = amount > 0 ? -1 : 1;
-        return advanceBusinessDays(date, direction, Math.abs(amount)).toString();
+        return stepBusinessDaysValue(value, amount, -1, calendar);
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return "";
     }
 }

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

@@ -3,10 +3,11 @@ import type { DateDurationUnit, Overflow } from "../../types/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`).
+ * - Accepts an RFC 9557 calendar-annotated PlainDate string (as `convertDateToCalendar` writes it),
+ *   not just a bare ISO string. See `addDate`'s JSDoc for the calendar-unit arithmetic (leap
+ *   months and years, the `overflow` asymmetry); this function is the mirror image.
+ * - Compatibility: since 1.16.0 calendar strings are RFC 9557 (ISO digits, `[u-ca=<id>]`, canonical
+ *   calendar ids); see `isValidCalendarDate`.
  * - Returns "" for invalid inputs.
  *
  * `overflow` ("constrain" (default) | "reject") controls out-of-range results, e.g. subtracting
@@ -17,10 +18,10 @@ import type { DateDurationUnit, Overflow } from "../../types/index.js";
  * @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-15", { days: 5 }) // "2024-03-10"
+ * @example subtractDate("invalid", { days: 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)
+ * @example subtractDate("2024-03-25[u-ca=hebrew]", { months: 1 }) // "2024-02-24[u-ca=hebrew]" (15 Adar II 5784 -> 15 Adar I)
  */
 export declare function subtractDate(value: string, units: Partial<Record<DateDurationUnit, number>>, options?: {
     overflow?: Overflow;

package/dist/plain/calculate/subtractDate.js

@@ -1,13 +1,17 @@
-import { calendarSystemOfDateValue, formatDateInCalendar, isValidAmount, parseCalendarDateValue, resolveOverflow, } from "../../internal/index.js";
+// fallow-ignore-file code-duplication -- sibling variant keeps its own guard, parse and try/catch, by design
+import { Temporal } from "@js-temporal/polyfill";
+import { calendarSystemOfDateValue, formatDateInCalendar, isValidAmount, parseCalendarDateValue, plainDateAdd, resolveOverflow, } from "../../internal/index.js";
 import { isValidCalendarDate, isValidDateDurationUnit } from "../validate/index.js";
+import { isOptionsArgument } from "../../internal/isObject.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`).
+ * - Accepts an RFC 9557 calendar-annotated PlainDate string (as `convertDateToCalendar` writes it),
+ *   not just a bare ISO string. See `addDate`'s JSDoc for the calendar-unit arithmetic (leap
+ *   months and years, the `overflow` asymmetry); this function is the mirror image.
+ * - Compatibility: since 1.16.0 calendar strings are RFC 9557 (ISO digits, `[u-ca=<id>]`, canonical
+ *   calendar ids); see `isValidCalendarDate`.
  * - Returns "" for invalid inputs.
  *
  * `overflow` ("constrain" (default) | "reject") controls out-of-range results, e.g. subtracting
@@ -18,30 +22,40 @@ import { isValidCalendarDate, isValidDateDurationUnit } from "../validate/index.
  * @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-15", { days: 5 }) // "2024-03-10"
+ * @example subtractDate("invalid", { days: 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)
+ * @example subtractDate("2024-03-25[u-ca=hebrew]", { months: 1 }) // "2024-02-24[u-ca=hebrew]" (15 Adar II 5784 -> 15 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) {
+        if (!isOptionsArgument(options)) {
+            return "";
+        }
+        const validDate = isValidCalendarDate(value);
+        const validUnits = typeof units === "object" &&
+            units !== null &&
+            Object.keys(units).every(isValidDateDurationUnit);
+        const validAmounts = validUnits && Object.values(units).every(isValidAmount);
+        if (!validDate || !validUnits || !validAmounts) {
+            return "";
+        }
+        try {
+            const calendar = calendarSystemOfDateValue(value);
+            if (!calendar) {
+                return "";
+            }
+            const date = parseCalendarDateValue(value);
+            const result = plainDateAdd(date, Temporal.Duration.from(units).negated(), resolveOverflow(options?.overflow));
+            return formatDateInCalendar(result, calendar);
+        }
+        catch {
             return "";
         }
-        const date = parseCalendarDateValue(value);
-        const result = date.subtract(units, {
-            overflow: resolveOverflow(options?.overflow),
-        });
-        return formatDateInCalendar(result, calendar);
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return "";
     }
 }

package/dist/plain/calculate/subtractDateTime.js

@@ -1,6 +1,8 @@
+// fallow-ignore-file code-duplication -- sibling variant keeps its own guard, parse and try/catch, by design
 import { Temporal } from "@js-temporal/polyfill";
 import { isValidAmount, resolveOverflow } from "../../internal/index.js";
 import { isValidDateTime, isValidDateTimeDurationUnit } from "../validate/index.js";
+import { isOptionsArgument } from "../../internal/isObject.js";
 /**
  * Return a PlainDateTime ISO string with `units` subtracted from `value`.
  *
@@ -20,19 +22,31 @@ import { isValidDateTime, isValidDateTimeDurationUnit } from "../validate/index.
  * @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();
+        if (!isOptionsArgument(options)) {
+            return "";
+        }
+        const validDateTime = isValidDateTime(value);
+        const validUnits = typeof units === "object" &&
+            units !== null &&
+            Object.keys(units).every(isValidDateTimeDurationUnit);
+        const validAmounts = validUnits && 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 "";
+        }
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return "";
     }
 }

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

@@ -1,22 +1,19 @@
-import type { Overflow, TimeDurationUnit } from "../../types/index.js";
+import type { 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.
+ * There is no options argument (its only member, `overflow`, was removed in 1.16.0): Temporal
+ * `PlainTime#subtract` takes no options and always wraps around the clock (e.g. 01:00 - 2 hours
+ * = 23:00).
  *
  * @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;
+export declare function subtractTime(value: string, units: Partial<Record<TimeDurationUnit, number>>): string;

package/dist/plain/calculate/subtractTime.js

@@ -1,5 +1,6 @@
+// fallow-ignore-file code-duplication -- sibling variant keeps its own guard, parse and try/catch, by design
 import { Temporal } from "@js-temporal/polyfill";
-import { isValidAmount, resolveOverflow } from "../../internal/index.js";
+import { isValidAmount } from "../../internal/index.js";
 import { isValidTime, isValidTimeDurationUnit } from "../validate/index.js";
 /**
  * Return a PlainTime ISO string with `units` subtracted from `value`.
@@ -7,32 +8,38 @@ import { isValidTime, isValidTimeDurationUnit } from "../validate/index.js";
  * - 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.
+ * There is no options argument (its only member, `overflow`, was removed in 1.16.0): Temporal
+ * `PlainTime#subtract` takes no options and always wraps around the clock (e.g. 01:00 - 2 hours
+ * = 23:00).
  *
  * @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 "";
-    }
+export function subtractTime(value, units) {
     try {
-        const time = Temporal.PlainTime.from(value);
-        return time
-            .subtract(units, { overflow: resolveOverflow(options?.overflow) })
-            .toString();
+        const validTime = isValidTime(value);
+        const validUnits = typeof units === "object" &&
+            units !== null &&
+            Object.keys(units).every(isValidTimeDurationUnit);
+        const validAmounts = validUnits && Object.values(units).every(isValidAmount);
+        if (!validTime || !validUnits || !validAmounts) {
+            return "";
+        }
+        try {
+            const time = Temporal.PlainTime.from(value);
+            return time.subtract(units).toString();
+        }
+        catch {
+            return "";
+        }
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return "";
     }
 }

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

@@ -1,4 +1,3 @@
-export * from "../../utc/chop/index.js";
 export * from "./chopDate.js";
 export * from "./chopMilliseconds.js";
 export * from "./chopSeconds.js";

package/dist/plain/chop/index.js

@@ -1,4 +1,3 @@
-export * from "../../utc/chop/index.js";
 export * from "./chopDate.js";
 export * from "./chopMilliseconds.js";
 export * from "./chopSeconds.js";

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

@@ -1,5 +1,4 @@
 import { Temporal } from "@js-temporal/polyfill";
-import type { FractionalDigit } from "../../types/index.js";
 /**
  * Compare two ISO datetime strings for equality at a given unit.
  *
@@ -9,7 +8,12 @@ import type { FractionalDigit } from "../../types/index.js";
  *   `dt.hasSame(other, "month")`.
  * - Supports the full `Temporal.DateUnit | Temporal.TimeUnit` range, down to
  *   `"nanosecond"`.
+ * - `unit` accepts the singular or plural name (`"day"` or `"days"`), as Temporal does.
+ * - `weekStartsOn` other than `"monday"` or `"sunday"` returns false.
  * - 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 (Decision 5, `context/roadmap/issues/J.md`):
  * - `isSameDay(a, b)` → `areDateTimesEqualBy(a, b, "day")`
@@ -21,17 +25,18 @@ import type { FractionalDigit } from "../../types/index.js";
  *
  * @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)
+ * @param unit date or time unit, singular or plural, to compare by
+ * @param optionsArg optional: weekStartsOn ("monday" | "sunday")
  * @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("2024-05-15T10:20:30.123", "2024-05-15T10:20:30.999", "milliseconds") // false (different milliseconds)
+ * @example areDateTimesEqualBy("2024-05-15T10:20:30.123", "2024-05-15T10:20:30.999", "second") // true
  * @example areDateTimesEqualBy("invalid", "2024-03-15T10:00:00", "day") // false
  */
-export declare function areDateTimesEqualBy(value1: string, value2: string, unit: Temporal.DateUnit | Temporal.TimeUnit, optionsArg?: {
+export declare function areDateTimesEqualBy(value1: string, value2: string, unit: Temporal.SmallestUnit<Temporal.DateTimeUnit>, optionsArg?: {
     weekStartsOn?: "monday" | "sunday";
-    fractionalSecondDigits?: FractionalDigit;
 }): boolean;

package/dist/plain/compare/areDateTimesEqualBy.js

@@ -1,6 +1,9 @@
 import { Temporal } from "@js-temporal/polyfill";
+import { resolveDateTimeUnit } from "../../internal/resolveDateTimeUnit.js";
+import { resolveWeekStartsOn } from "../../internal/resolveWeekStartsOn.js";
 import { startOfDateTime } from "../calculate/startOfDateTime.js";
 import { isValidDateTime, isValidDateTimeUnit } from "../validate/index.js";
+import { isOptionsArgument } from "../../internal/isObject.js";
 /**
  * Compare two ISO datetime strings for equality at a given unit.
  *
@@ -10,7 +13,12 @@ import { isValidDateTime, isValidDateTimeUnit } from "../validate/index.js";
  *   `dt.hasSame(other, "month")`.
  * - Supports the full `Temporal.DateUnit | Temporal.TimeUnit` range, down to
  *   `"nanosecond"`.
+ * - `unit` accepts the singular or plural name (`"day"` or `"days"`), as Temporal does.
+ * - `weekStartsOn` other than `"monday"` or `"sunday"` returns false.
  * - 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 (Decision 5, `context/roadmap/issues/J.md`):
  * - `isSameDay(a, b)` → `areDateTimesEqualBy(a, b, "day")`
@@ -22,28 +30,45 @@ import { isValidDateTime, isValidDateTimeUnit } from "../validate/index.js";
  *
  * @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)
+ * @param unit date or time unit, singular or plural, to compare by
+ * @param optionsArg optional: weekStartsOn ("monday" | "sunday")
  * @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("2024-05-15T10:20:30.123", "2024-05-15T10:20:30.999", "milliseconds") // false (different milliseconds)
+ * @example areDateTimesEqualBy("2024-05-15T10:20:30.123", "2024-05-15T10:20:30.999", "second") // true
  * @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;
+        if (!isOptionsArgument(optionsArg)) {
+            return false;
+        }
+        const resolvedUnit = resolveDateTimeUnit(unit);
+        const weekStartsOn = resolveWeekStartsOn(optionsArg?.weekStartsOn);
+        if (!isValidDateTime(value1) ||
+            !isValidDateTime(value2) ||
+            !isValidDateTimeUnit(resolvedUnit) ||
+            weekStartsOn === null) {
+            return false;
+        }
+        try {
+            const start1 = startOfDateTime(value1, resolvedUnit, { weekStartsOn });
+            const start2 = startOfDateTime(value2, resolvedUnit, { weekStartsOn });
+            if (start1 === "" || start2 === "")
+                return false;
+            return (Temporal.PlainDateTime.compare(Temporal.PlainDateTime.from(start1), Temporal.PlainDateTime.from(start2)) === 0);
+        }
+        catch {
+            return false;
+        }
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return false;
     }
 }

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

@@ -7,8 +7,13 @@ import { Temporal } from "@js-temporal/polyfill";
  *   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`.
+ * - `"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.
+ * - `weekStartsOn` other than `"monday"` or `"sunday"` returns false.
  * - Returns false for an unsupported unit or invalid input.
  *
  * Mapping from date-fns (Decision 5, `context/roadmap/issues/J.md`):
@@ -19,16 +24,18 @@ import { Temporal } from "@js-temporal/polyfill";
  *
  * @param value1 first ISO date string
  * @param value2 second ISO date string
- * @param unit Temporal.DateUnit to compare by ("year" | "month" | "week" | "day")
+ * @param unit date unit to compare by ("year" | "month" | "week" | "day", or its plural)
  * @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("2024-03-15", "2024-03-20", "months") // true
+ * @example areDatesEqualBy("2024-03-15", "2024-03-20", "week", { weekStartsOn: "tuesday" }) // false (invalid weekStartsOn)
  * @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?: {
+export declare function areDatesEqualBy(value1: string, value2: string, unit: Temporal.SmallestUnit<Temporal.DateUnit>, optionsArg?: {
     weekStartsOn?: "monday" | "sunday";
 }): boolean;

package/dist/plain/compare/areDatesEqualBy.js

@@ -1,7 +1,10 @@
 import { Temporal } from "@js-temporal/polyfill";
+import { resolveDateTimeUnit } from "../../internal/resolveDateTimeUnit.js";
+import { resolveWeekStartsOn } from "../../internal/resolveWeekStartsOn.js";
 import { startOfDate } from "../calculate/startOfDate.js";
 import { isValidDate } from "../validate/index.js";
 import { areDatesEqual } from "./areDatesEqual.js";
+import { isOptionsArgument } from "../../internal/isObject.js";
 const supported = ["year", "month", "week", "day"];
 /**
  * Compare two ISO date strings for equality at a given calendar unit.
@@ -11,8 +14,13 @@ const supported = ["year", "month", "week", "day"];
  *   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`.
+ * - `"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.
+ * - `weekStartsOn` other than `"monday"` or `"sunday"` returns false.
  * - Returns false for an unsupported unit or invalid input.
  *
  * Mapping from date-fns (Decision 5, `context/roadmap/issues/J.md`):
@@ -23,32 +31,51 @@ const supported = ["year", "month", "week", "day"];
  *
  * @param value1 first ISO date string
  * @param value2 second ISO date string
- * @param unit Temporal.DateUnit to compare by ("year" | "month" | "week" | "day")
+ * @param unit date unit to compare by ("year" | "month" | "week" | "day", or its plural)
  * @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("2024-03-15", "2024-03-20", "months") // true
+ * @example areDatesEqualBy("2024-03-15", "2024-03-20", "week", { weekStartsOn: "tuesday" }) // false (invalid weekStartsOn)
  * @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 function areDatesEqualBy(value1, value2, unit, optionsArg) {
-    if (!isValidDate(value1) ||
-        !isValidDate(value2) ||
-        !supported.includes(unit)) {
-        return false;
-    }
-    // "day" has no coarser boundary to reset, so this is just direct equality.
-    if (unit === "day") {
-        return areDatesEqual(value1, value2);
-    }
     try {
-        const start1 = startOfDate(value1, unit, optionsArg);
-        const start2 = startOfDate(value2, unit, optionsArg);
-        return start1 !== "" && start1 === start2;
+        if (!isOptionsArgument(optionsArg)) {
+            return false;
+        }
+        const resolvedUnit = resolveDateTimeUnit(unit);
+        const weekStartsOn = resolveWeekStartsOn(optionsArg?.weekStartsOn);
+        if (!isValidDate(value1) ||
+            !isValidDate(value2) ||
+            !supported.includes(resolvedUnit) ||
+            weekStartsOn === null) {
+            return false;
+        }
+        // "day" has no coarser boundary to reset, so this is just direct equality.
+        if (resolvedUnit === "day") {
+            return areDatesEqual(value1, value2);
+        }
+        try {
+            const start1 = startOfDate(value1, resolvedUnit, {
+                weekStartsOn,
+            });
+            const start2 = startOfDate(value2, resolvedUnit, {
+                weekStartsOn,
+            });
+            return start1 !== "" && start1 === start2;
+        }
+        catch {
+            return false;
+        }
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return false;
     }
 }