@northguild/gmt 1.14.2 → 1.16.0

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;
     }
 }

package/dist/plain/compare/isBetweenDate.js

@@ -1,5 +1,7 @@
+// fallow-ignore-file code-duplication -- cross-family Temporal type clone, by design (rule 5)
 import { Temporal } from "@js-temporal/polyfill";
 import { isValidDate } from "../validate/index.js";
+import { isOptionsArgument } from "../../internal/isObject.js";
 /**
  * Return true when `date` is between `start` and `end` (inclusive by default).
  *
@@ -23,27 +25,41 @@ import { isValidDate } from "../validate/index.js";
  * @example isBetweenDate("2024-02-29", "2024-02-01", "invalid") // false
  */
 export function isBetweenDate(date, start, end, options) {
-    const inclusiveStart = options?.inclusiveStart ?? true;
-    const inclusiveEnd = options?.inclusiveEnd ?? true;
-    if (!isValidDate(date) || !isValidDate(start) || !isValidDate(end)) {
-        return false;
-    }
     try {
-        const d = Temporal.PlainDate.from(date);
-        const s = Temporal.PlainDate.from(start);
-        const e = Temporal.PlainDate.from(end);
-        if (Temporal.PlainDate.compare(s, e) === 1) {
+        if (!isOptionsArgument(options)) {
+            return false;
+        }
+        // Only an omitted flag takes the `true` default. An explicit `null` is a value, and every
+        // reading of it gives `false`: ECMA-402 reads a boolean option through ToBoolean (null → false),
+        // and the house rule rejects an invalid member outright — neither yields `true`. So `null`
+        // behaves here exactly as `0` and `""` already do.
+        const inclusiveStart = options?.inclusiveStart === undefined ? true : options.inclusiveStart;
+        const inclusiveEnd = options?.inclusiveEnd === undefined ? true : options.inclusiveEnd;
+        if (!isValidDate(date) || !isValidDate(start) || !isValidDate(end)) {
+            return false;
+        }
+        try {
+            const d = Temporal.PlainDate.from(date);
+            const s = Temporal.PlainDate.from(start);
+            const e = Temporal.PlainDate.from(end);
+            if (Temporal.PlainDate.compare(s, e) === 1) {
+                return false;
+            }
+            const startCheck = inclusiveStart
+                ? Temporal.PlainDate.compare(s, d) <= 0
+                : Temporal.PlainDate.compare(s, d) < 0;
+            const endCheck = inclusiveEnd
+                ? Temporal.PlainDate.compare(d, e) <= 0
+                : Temporal.PlainDate.compare(d, e) < 0;
+            return startCheck && endCheck;
+        }
+        catch {
             return false;
         }
-        const startCheck = inclusiveStart
-            ? Temporal.PlainDate.compare(s, d) <= 0
-            : Temporal.PlainDate.compare(s, d) < 0;
-        const endCheck = inclusiveEnd
-            ? Temporal.PlainDate.compare(d, e) <= 0
-            : Temporal.PlainDate.compare(d, e) < 0;
-        return startCheck && endCheck;
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return false;
     }
 }

package/dist/plain/compare/isBetweenDateTime.js

@@ -1,5 +1,7 @@
+// fallow-ignore-file code-duplication -- cross-family Temporal type clone, by design (rule 5)
 import { Temporal } from "@js-temporal/polyfill";
 import { isValidDateTime } from "../validate/index.js";
+import { isOptionsArgument } from "../../internal/isObject.js";
 /**
  * Return true when `dateTime` is between `start` and `end` (inclusive by default).
  *
@@ -23,29 +25,43 @@ import { isValidDateTime } from "../validate/index.js";
  * @example isBetweenDateTime("2024-02-29T12:00:00", "2024-02-01T00:00:00", "invalid") // false
  */
 export function isBetweenDateTime(dateTime, start, end, options) {
-    const inclusiveStart = options?.inclusiveStart ?? true;
-    const inclusiveEnd = options?.inclusiveEnd ?? true;
-    if (!isValidDateTime(dateTime) ||
-        !isValidDateTime(start) ||
-        !isValidDateTime(end)) {
-        return false;
-    }
     try {
-        const d = Temporal.PlainDateTime.from(dateTime);
-        const s = Temporal.PlainDateTime.from(start);
-        const e = Temporal.PlainDateTime.from(end);
-        if (Temporal.PlainDateTime.compare(s, e) === 1) {
+        if (!isOptionsArgument(options)) {
+            return false;
+        }
+        // Only an omitted flag takes the `true` default. An explicit `null` is a value, and every
+        // reading of it gives `false`: ECMA-402 reads a boolean option through ToBoolean (null → false),
+        // and the house rule rejects an invalid member outright — neither yields `true`. So `null`
+        // behaves here exactly as `0` and `""` already do.
+        const inclusiveStart = options?.inclusiveStart === undefined ? true : options.inclusiveStart;
+        const inclusiveEnd = options?.inclusiveEnd === undefined ? true : options.inclusiveEnd;
+        if (!isValidDateTime(dateTime) ||
+            !isValidDateTime(start) ||
+            !isValidDateTime(end)) {
+            return false;
+        }
+        try {
+            const d = Temporal.PlainDateTime.from(dateTime);
+            const s = Temporal.PlainDateTime.from(start);
+            const e = Temporal.PlainDateTime.from(end);
+            if (Temporal.PlainDateTime.compare(s, e) === 1) {
+                return false;
+            }
+            const startCheck = inclusiveStart
+                ? Temporal.PlainDateTime.compare(s, d) <= 0
+                : Temporal.PlainDateTime.compare(s, d) < 0;
+            const endCheck = inclusiveEnd
+                ? Temporal.PlainDateTime.compare(d, e) <= 0
+                : Temporal.PlainDateTime.compare(d, e) < 0;
+            return startCheck && endCheck;
+        }
+        catch {
             return false;
         }
-        const startCheck = inclusiveStart
-            ? Temporal.PlainDateTime.compare(s, d) <= 0
-            : Temporal.PlainDateTime.compare(s, d) < 0;
-        const endCheck = inclusiveEnd
-            ? Temporal.PlainDateTime.compare(d, e) <= 0
-            : Temporal.PlainDateTime.compare(d, e) < 0;
-        return startCheck && endCheck;
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return false;
     }
 }

package/dist/plain/compare/isBetweenTime.js

@@ -1,5 +1,7 @@
+// fallow-ignore-file code-duplication -- cross-family Temporal type clone, by design (rule 5)
 import { Temporal } from "@js-temporal/polyfill";
 import { isValidTime } from "../validate/index.js";
+import { isOptionsArgument } from "../../internal/isObject.js";
 /**
  * Return true when `time` is between `start` and `end` (inclusive by default).
  *
@@ -25,27 +27,41 @@ import { isValidTime } from "../validate/index.js";
  * @example isBetweenTime("12:34:56", "12:00:00", "invalid") // false
  */
 export function isBetweenTime(time, start, end, options) {
-    const inclusiveStart = options?.inclusiveStart ?? true;
-    const inclusiveEnd = options?.inclusiveEnd ?? true;
-    if (!isValidTime(time) || !isValidTime(start) || !isValidTime(end)) {
-        return false;
-    }
     try {
-        const t = Temporal.PlainTime.from(time);
-        const s = Temporal.PlainTime.from(start);
-        const e = Temporal.PlainTime.from(end);
-        if (Temporal.PlainTime.compare(s, e) === 1) {
+        if (!isOptionsArgument(options)) {
+            return false;
+        }
+        // Only an omitted flag takes the `true` default. An explicit `null` is a value, and every
+        // reading of it gives `false`: ECMA-402 reads a boolean option through ToBoolean (null → false),
+        // and the house rule rejects an invalid member outright — neither yields `true`. So `null`
+        // behaves here exactly as `0` and `""` already do.
+        const inclusiveStart = options?.inclusiveStart === undefined ? true : options.inclusiveStart;
+        const inclusiveEnd = options?.inclusiveEnd === undefined ? true : options.inclusiveEnd;
+        if (!isValidTime(time) || !isValidTime(start) || !isValidTime(end)) {
+            return false;
+        }
+        try {
+            const t = Temporal.PlainTime.from(time);
+            const s = Temporal.PlainTime.from(start);
+            const e = Temporal.PlainTime.from(end);
+            if (Temporal.PlainTime.compare(s, e) === 1) {
+                return false;
+            }
+            const startCheck = inclusiveStart
+                ? Temporal.PlainTime.compare(s, t) <= 0
+                : Temporal.PlainTime.compare(s, t) < 0;
+            const endCheck = inclusiveEnd
+                ? Temporal.PlainTime.compare(t, e) <= 0
+                : Temporal.PlainTime.compare(t, e) < 0;
+            return startCheck && endCheck;
+        }
+        catch {
             return false;
         }
-        const startCheck = inclusiveStart
-            ? Temporal.PlainTime.compare(s, t) <= 0
-            : Temporal.PlainTime.compare(s, t) < 0;
-        const endCheck = inclusiveEnd
-            ? Temporal.PlainTime.compare(t, e) <= 0
-            : Temporal.PlainTime.compare(t, e) < 0;
-        return startCheck && endCheck;
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return false;
     }
 }

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

@@ -1,21 +1,35 @@
+import type { BusinessCalendar } from "../../types/index.js";
 /**
- * Return true when `value` falls on a Monday–Friday ISO business day.
+ * Return true when `value` is a working day in `calendar`.
  *
- * - Uses the fixed ISO Monday–Friday business-day boundary (Mon=1 … Fri=5),
- *   matching the definition used by `addBusinessDays`/`subtractBusinessDays`.
- * - Locale-agnostic: no `Intl.Locale` lookup and no holiday calendar.
- * - Returns false if `value` is invalid.
+ * - `calendar` names the weekend days and holidays that make a date non-working. Omit it and
+ *   GMT keeps its original fixed Monday–Friday week with no holidays.
+ * - **Pass a calendar anywhere the weekend is not Saturday–Sunday.** Much of the Middle East
+ *   is Friday–Saturday and some markets keep a one-day weekend; the no-calendar form assumes
+ *   Saturday–Sunday and is wrong for them.
+ * - `value` and `calendar.holidays` are local dates. `calendar.timeZone` is not read: it
+ *   records which locality the calendar describes, so that a caller holding an *instant* knows
+ *   which zone to reduce it in — with `floorToZone` or `getZonedDateTimeFields` — before
+ *   asking this question.
+ * - Returns false if `value` is not a valid ISO PlainDate, or `calendar` is not a valid
+ *   `BusinessCalendar`. Narrow a calendar first with `isValidBusinessCalendar` to tell a
+ *   misconfigured calendar apart from a genuine non-working day.
  *
- * This is the locale-agnostic complement to the locale-aware `isWeekend`: `isWeekend`
- * resolves weekend days per locale via `Intl.Locale.prototype.weekInfo`, whereas
- * `isBusinessDay` always treats Monday–Friday as business days regardless of locale.
+ * This is the locale-agnostic complement to the locale-aware `isWeekend`: `isWeekend` resolves
+ * weekend days per locale via `Intl.Locale.prototype.weekInfo`, whereas `isBusinessDay` uses
+ * the weekend the caller states, or Monday–Friday when they state none.
  *
  * @param value ISO PlainDate string
- * @returns true if `value` is a Monday–Friday business day, false on invalid input
+ * @param calendar optional BusinessCalendar; defaults to Monday–Friday with no holidays
+ * @returns true if `value` is a working day, false on invalid input
  *
  * @example isBusinessDay("2024-02-05") // true (Monday)
  * @example isBusinessDay("2024-02-10") // false (Saturday)
- * @example isBusinessDay("2024-02-04") // false (Sunday)
+ * @example isBusinessDay("2024-07-04", { weekend: [6, 7], holidays: ["2024-07-04"], timeZone: "America/New_York" }) // false (holiday)
+ * @example isBusinessDay("2024-07-05", { weekend: [6, 7], holidays: ["2024-07-04"], timeZone: "America/New_York" }) // true
+ * @example isBusinessDay("2024-07-07", { weekend: [5, 6], holidays: [], timeZone: "Asia/Riyadh" }) // true (Sunday is a working day there)
+ * @example isBusinessDay("2024-07-05", { weekend: [5, 6], holidays: [], timeZone: "Asia/Riyadh" }) // false (Friday is weekend there)
  * @example isBusinessDay("invalid") // false
+ * @example isBusinessDay("2024-02-05", { weekend: [6, 7], holidays: [], timeZone: "Invalid/Zone" }) // false (bad calendar)
  */
-export declare function isBusinessDay(value: string): boolean;
+export declare function isBusinessDay(value: string, calendar?: BusinessCalendar): boolean;

package/dist/plain/compare/isBusinessDay.js

@@ -1,33 +1,54 @@
 import { Temporal } from "@js-temporal/polyfill";
+import { isBusinessDate, resolveBusinessCalendar, } from "../../internal/businessCalendar.js";
 import { isValidDate } from "../validate/index.js";
 /**
- * Return true when `value` falls on a Monday–Friday ISO business day.
+ * Return true when `value` is a working day in `calendar`.
  *
- * - Uses the fixed ISO Monday–Friday business-day boundary (Mon=1 … Fri=5),
- *   matching the definition used by `addBusinessDays`/`subtractBusinessDays`.
- * - Locale-agnostic: no `Intl.Locale` lookup and no holiday calendar.
- * - Returns false if `value` is invalid.
+ * - `calendar` names the weekend days and holidays that make a date non-working. Omit it and
+ *   GMT keeps its original fixed Monday–Friday week with no holidays.
+ * - **Pass a calendar anywhere the weekend is not Saturday–Sunday.** Much of the Middle East
+ *   is Friday–Saturday and some markets keep a one-day weekend; the no-calendar form assumes
+ *   Saturday–Sunday and is wrong for them.
+ * - `value` and `calendar.holidays` are local dates. `calendar.timeZone` is not read: it
+ *   records which locality the calendar describes, so that a caller holding an *instant* knows
+ *   which zone to reduce it in — with `floorToZone` or `getZonedDateTimeFields` — before
+ *   asking this question.
+ * - Returns false if `value` is not a valid ISO PlainDate, or `calendar` is not a valid
+ *   `BusinessCalendar`. Narrow a calendar first with `isValidBusinessCalendar` to tell a
+ *   misconfigured calendar apart from a genuine non-working day.
  *
- * This is the locale-agnostic complement to the locale-aware `isWeekend`: `isWeekend`
- * resolves weekend days per locale via `Intl.Locale.prototype.weekInfo`, whereas
- * `isBusinessDay` always treats Monday–Friday as business days regardless of locale.
+ * This is the locale-agnostic complement to the locale-aware `isWeekend`: `isWeekend` resolves
+ * weekend days per locale via `Intl.Locale.prototype.weekInfo`, whereas `isBusinessDay` uses
+ * the weekend the caller states, or Monday–Friday when they state none.
  *
  * @param value ISO PlainDate string
- * @returns true if `value` is a Monday–Friday business day, false on invalid input
+ * @param calendar optional BusinessCalendar; defaults to Monday–Friday with no holidays
+ * @returns true if `value` is a working day, false on invalid input
  *
  * @example isBusinessDay("2024-02-05") // true (Monday)
  * @example isBusinessDay("2024-02-10") // false (Saturday)
- * @example isBusinessDay("2024-02-04") // false (Sunday)
+ * @example isBusinessDay("2024-07-04", { weekend: [6, 7], holidays: ["2024-07-04"], timeZone: "America/New_York" }) // false (holiday)
+ * @example isBusinessDay("2024-07-05", { weekend: [6, 7], holidays: ["2024-07-04"], timeZone: "America/New_York" }) // true
+ * @example isBusinessDay("2024-07-07", { weekend: [5, 6], holidays: [], timeZone: "Asia/Riyadh" }) // true (Sunday is a working day there)
+ * @example isBusinessDay("2024-07-05", { weekend: [5, 6], holidays: [], timeZone: "Asia/Riyadh" }) // false (Friday is weekend there)
  * @example isBusinessDay("invalid") // false
+ * @example isBusinessDay("2024-02-05", { weekend: [6, 7], holidays: [], timeZone: "Invalid/Zone" }) // false (bad calendar)
  */
-export function isBusinessDay(value) {
-    if (!isValidDate(value))
-        return false;
+export function isBusinessDay(value, calendar) {
     try {
-        const date = Temporal.PlainDate.from(value);
-        return date.dayOfWeek >= 1 && date.dayOfWeek <= 5;
+        const resolved = resolveBusinessCalendar(calendar);
+        if (!isValidDate(value) || resolved === null)
+            return false;
+        try {
+            return isBusinessDate(Temporal.PlainDate.from(value), resolved);
+        }
+        catch {
+            return false;
+        }
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return false;
     }
 }

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

@@ -14,7 +14,12 @@ import type { Temporal } from "@js-temporal/polyfill";
  *   system timeZone**. A caller needing determinism should use
  *   `isZonedThisUnit` with an explicit timeZone, or compare against an
  *   explicit reference with `areDatesEqualBy`.
- * - Returns false for an unsupported unit, invalid input, or an invalid locale.
+ * - `unit` accepts the singular or plural name (`"month"` or `"months"`), as Temporal does.
+ * - `locale` may be a BCP 47 tag or a preference list of tags (ECMA-402); the first tag with locale
+ *   data sets the week start.
+ * - Returns false for an unsupported unit or invalid input. The locale is validated for every
+ *   unit, so an invalid locale returns false for `"day"`, `"month"` and `"year"` too.
+ * - **Compatibility:** before 1.16.0 an invalid locale was ignored for every unit but `"week"`.
  *
  * Mapping from date-fns (Decision 5, `context/roadmap/issues/J.md`):
  * - `isThisWeek(value, options)` → `isThisUnit(value, "week", locale)`
@@ -22,8 +27,8 @@ import type { Temporal } from "@js-temporal/polyfill";
  * - `isThisYear(value)` → `isThisUnit(value, "year")`
  *
  * @param value ISO PlainDate string
- * @param unit Temporal.DateUnit to compare by ("year" | "month" | "week" | "day")
- * @param locale optional BCP 47 locale tag — only affects the "week" case (e.g. "en-US", "fr-FR")
+ * @param unit date unit to compare by ("year" | "month" | "week" | "day", or its plural)
+ * @param locale optional BCP 47 locale tag or preference list — sets the "week" start (e.g. "en-US", ["fr-FR", "en-US"])
  * @returns true if `value` falls in the same `unit` as today, false on an unsupported unit or invalid input
  *
  * @example isThisUnit("2024-03-15", "month") // true, if today is any day in March 2024
@@ -31,5 +36,9 @@ import type { Temporal } from "@js-temporal/polyfill";
  * @example isThisUnit("2024-02-26", "week", "fr-FR") // true, if today is 2024-03-01 (same fr-FR Monday-start week)
  * @example isThisUnit("2024-03-15", "hour" as never) // false (unsupported unit)
  * @example isThisUnit("invalid", "month") // false
+ * @example isThisUnit("2024-03-15", "week", "not-a-locale-!!") // false (invalid locale)
+ * @example isThisUnit("2024-03-15", "day", "not-a-locale-!!") // false (invalid locale, for every unit)
+ * @example isThisUnit("2024-03-15", "months") // true, if today is any day in March 2024
+ * @example isThisUnit("2024-02-25", "week", ["en-US", "fr-FR"]) // true, if today is 2024-02-29 (en-US Sunday-start week)
  */
-export declare function isThisUnit(value: string, unit: Temporal.DateUnit, locale?: string): boolean;
+export declare function isThisUnit(value: string, unit: Temporal.SmallestUnit<Temporal.DateUnit>, locale?: string | string[]): boolean;

package/dist/plain/compare/isThisUnit.js

@@ -1,3 +1,5 @@
+import { resolveDateTimeUnit } from "../../internal/resolveDateTimeUnit.js";
+import { resolveLocale } from "../../internal/resolveLocale.js";
 import { getLocaleStartOfWeek } from "../calculate/getLocaleStartOfWeek.js";
 import { getToday } from "../get/getToday.js";
 import { isValidDateUnit } from "../validate/index.js";
@@ -17,7 +19,12 @@ import { areDatesEqualBy } from "./areDatesEqualBy.js";
  *   system timeZone**. A caller needing determinism should use
  *   `isZonedThisUnit` with an explicit timeZone, or compare against an
  *   explicit reference with `areDatesEqualBy`.
- * - Returns false for an unsupported unit, invalid input, or an invalid locale.
+ * - `unit` accepts the singular or plural name (`"month"` or `"months"`), as Temporal does.
+ * - `locale` may be a BCP 47 tag or a preference list of tags (ECMA-402); the first tag with locale
+ *   data sets the week start.
+ * - Returns false for an unsupported unit or invalid input. The locale is validated for every
+ *   unit, so an invalid locale returns false for `"day"`, `"month"` and `"year"` too.
+ * - **Compatibility:** before 1.16.0 an invalid locale was ignored for every unit but `"week"`.
  *
  * Mapping from date-fns (Decision 5, `context/roadmap/issues/J.md`):
  * - `isThisWeek(value, options)` → `isThisUnit(value, "week", locale)`
@@ -25,8 +32,8 @@ import { areDatesEqualBy } from "./areDatesEqualBy.js";
  * - `isThisYear(value)` → `isThisUnit(value, "year")`
  *
  * @param value ISO PlainDate string
- * @param unit Temporal.DateUnit to compare by ("year" | "month" | "week" | "day")
- * @param locale optional BCP 47 locale tag — only affects the "week" case (e.g. "en-US", "fr-FR")
+ * @param unit date unit to compare by ("year" | "month" | "week" | "day", or its plural)
+ * @param locale optional BCP 47 locale tag or preference list — sets the "week" start (e.g. "en-US", ["fr-FR", "en-US"])
  * @returns true if `value` falls in the same `unit` as today, false on an unsupported unit or invalid input
  *
  * @example isThisUnit("2024-03-15", "month") // true, if today is any day in March 2024
@@ -34,19 +41,32 @@ import { areDatesEqualBy } from "./areDatesEqualBy.js";
  * @example isThisUnit("2024-02-26", "week", "fr-FR") // true, if today is 2024-03-01 (same fr-FR Monday-start week)
  * @example isThisUnit("2024-03-15", "hour" as never) // false (unsupported unit)
  * @example isThisUnit("invalid", "month") // false
+ * @example isThisUnit("2024-03-15", "week", "not-a-locale-!!") // false (invalid locale)
+ * @example isThisUnit("2024-03-15", "day", "not-a-locale-!!") // false (invalid locale, for every unit)
+ * @example isThisUnit("2024-03-15", "months") // true, if today is any day in March 2024
+ * @example isThisUnit("2024-02-25", "week", ["en-US", "fr-FR"]) // true, if today is 2024-02-29 (en-US Sunday-start week)
  */
 export function isThisUnit(value, unit, locale) {
-    if (!isValidDateUnit(unit)) {
-        return false;
+    try {
+        const resolvedUnit = resolveDateTimeUnit(unit);
+        if (!isValidDateUnit(resolvedUnit) ||
+            (locale !== undefined && resolveLocale(locale) === null)) {
+            return false;
+        }
+        const today = getToday();
+        if (today === "") {
+            return false;
+        }
+        if (resolvedUnit === "week" && locale !== undefined) {
+            const startOfWeekValue = getLocaleStartOfWeek(value, locale);
+            const startOfWeekToday = getLocaleStartOfWeek(today, locale);
+            return startOfWeekValue !== "" && startOfWeekValue === startOfWeekToday;
+        }
+        return areDatesEqualBy(value, today, resolvedUnit);
     }
-    const today = getToday();
-    if (today === "") {
+    catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return false;
     }
-    if (unit === "week" && locale !== undefined) {
-        const startOfWeekValue = getLocaleStartOfWeek(value, locale);
-        const startOfWeekToday = getLocaleStartOfWeek(today, locale);
-        return startOfWeekValue !== "" && startOfWeekValue === startOfWeekToday;
-    }
-    return areDatesEqualBy(value, today, unit);
 }

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

@@ -6,16 +6,20 @@
  *   he-IL/ar-SA: Fri/Sat).
  * - Falls back to Saturday/Sunday if the runtime's `weekInfo` data doesn't
  *   resolve a weekend for the locale.
- * - Returns false if `value` or `locale` is invalid.
+ * - Returns false if `value` is invalid or `locale` is not a well-formed BCP 47 tag
+ *   (ECMA-402 `IsWellFormedLanguageTag`).
+ *   A well-formed tag with no matching locale data is not an error: it falls back to the host's
+ *   default locale, as ECMA-402 `ResolveLocale` requires.
  *
  * @param value ISO PlainDate string
- * @param locale BCP 47 locale tag (e.g. "en-US", "he-IL")
+ * @param locale BCP 47 locale tag (e.g. "en-US", "he-IL"), or a preference list of tags (ECMA-402; the first with locale data is read). Required: omitted, or an empty list (which ECMA-402 would resolve to the host default), returns false
  * @returns true if `value` is a weekend day in `locale`, false on invalid input
  *
  * @example isWeekend("2024-02-03", "en-US") // true (Saturday, en-US weekend is Sat/Sun)
  * @example isWeekend("2024-02-02", "he-IL") // true (Friday, he-IL weekend is Fri/Sat)
  * @example isWeekend("2024-02-04", "he-IL") // false (Sunday, not part of he-IL's weekend)
  * @example isWeekend("invalid", "en-US") // false
- * @example isWeekend("2024-02-03", "not-a-locale") // false
+ * @example isWeekend("2024-02-03", "not-a-locale-!!") // false
+ * @example isWeekend("2024-05-17", ["ar-EG", "fr-FR"]) // true (Friday is an ar-EG weekend day)
  */
-export declare function isWeekend(value: string, locale: string): boolean;
+export declare function isWeekend(value: string, locale: string | string[]): boolean;

package/dist/plain/compare/isWeekend.js

@@ -9,17 +9,21 @@ import { isValidDate } from "../validate/index.js";
  *   he-IL/ar-SA: Fri/Sat).
  * - Falls back to Saturday/Sunday if the runtime's `weekInfo` data doesn't
  *   resolve a weekend for the locale.
- * - Returns false if `value` or `locale` is invalid.
+ * - Returns false if `value` is invalid or `locale` is not a well-formed BCP 47 tag
+ *   (ECMA-402 `IsWellFormedLanguageTag`).
+ *   A well-formed tag with no matching locale data is not an error: it falls back to the host's
+ *   default locale, as ECMA-402 `ResolveLocale` requires.
  *
  * @param value ISO PlainDate string
- * @param locale BCP 47 locale tag (e.g. "en-US", "he-IL")
+ * @param locale BCP 47 locale tag (e.g. "en-US", "he-IL"), or a preference list of tags (ECMA-402; the first with locale data is read). Required: omitted, or an empty list (which ECMA-402 would resolve to the host default), returns false
  * @returns true if `value` is a weekend day in `locale`, false on invalid input
  *
  * @example isWeekend("2024-02-03", "en-US") // true (Saturday, en-US weekend is Sat/Sun)
  * @example isWeekend("2024-02-02", "he-IL") // true (Friday, he-IL weekend is Fri/Sat)
  * @example isWeekend("2024-02-04", "he-IL") // false (Sunday, not part of he-IL's weekend)
  * @example isWeekend("invalid", "en-US") // false
- * @example isWeekend("2024-02-03", "not-a-locale") // false
+ * @example isWeekend("2024-02-03", "not-a-locale-!!") // false
+ * @example isWeekend("2024-05-17", ["ar-EG", "fr-FR"]) // true (Friday is an ar-EG weekend day)
  */
 export function isWeekend(value, locale) {
     if (!isValidDate(value))