@northguild/gmt 1.15.0 → 1.17.0

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))

package/dist/plain/convert/convertDateToCalendar.d.ts

@@ -1,44 +1,45 @@
 import type { CalendarSystem } from "../../types/index.js";
 /**
- * Convert a PlainDate to the same date expressed in a different calendar system.
+ * Express a PlainDate in a calendar system: the RFC 9557 string
+ * `Temporal.PlainDate#toString()` writes for that date in that calendar.
  *
- * - Accepts a plain ISO date ("2024-10-03") or a calendar-annotated date previously
- *   produced by this function ("5785-01-01[u-ca=hebrew]"), so conversions can chain
- *   between calendar systems.
- * - The output for "gregorian" is always a bare, unannotated ISO string, matching every
- *   other GMT PlainDate string. Any other calendar returns its own native year/month/day
- *   (e.g. Hebrew year 5785, not the ISO year), tagged with `[u-ca=<identifier>]` — this
- *   diverges from Temporal's own `[u-ca=...]` string convention (which keeps ISO digits
- *   and only annotates the calendar) specifically so the calendar's native fields are
- *   visible in GMT's string contract, not hidden behind calendar-aware accessors.
- * - Uses Temporal's built-in calendar support (`PlainDate.prototype.withCalendar`) for every
- *   calendar except the Ethiopic family ("ethiopic" / "ethiopic-amete-alem" / "coptic"),
- *   which is computed with GMT-owned arithmetic instead — see
- *   `internal/ethiopicFamilyCalendar.ts` for why. Either way, the underlying date never
- *   changes, only which calendar's fields it resolves through.
+ * - The date never changes, and neither do its digits: they are always the ISO 8601 date.
+ *   The calendar is carried by a `[u-ca=<id>]` annotation (RFC 9557 §3.3), and eras, calendar
+ *   years and month codes are never part of the string.
+ * - `"iso8601"` writes a bare ISO date; every other calendar, `"gregory"` included, is annotated.
+ * - Accepts a bare ISO date or any calendar-annotated date GMT reads (see `isValidCalendarDate`),
+ *   so conversions chain between calendars.
+ * - `calendar` is a canonical calendar id; like Temporal's `withCalendar`, an alias or another
+ *   letter case is canonicalized (`"ethiopic-amete-alem"` writes `[u-ca=ethioaa]`).
+ * - **Only one of CLDR's four legacy calendar aliases works, and that is Temporal's rule, not
+ *   GMT's.** `ethiopic-amete-alem` canonicalizes to `ethioaa`; `gregorian`, `islamic-tabular` and
+ *   `taiwan` return `""`. Chromium 153 and `@js-temporal/polyfill` both throw `RangeError` for
+ *   those three: `gregorian` is nine letters, past the 8-character limit on a Unicode
+ *   locale-extension `type` subtag, and the other two are absent from ECMA-402's
+ *   `AvailableCanonicalCalendars`. Use `gregory`, `islamic-tbla` and `roc`.
  * - Returns "" on invalid input or an unsupported `calendar`.
  *
- * "japanese" and "ethiopic" are the two calendars tagged with an era instead of a plain
- * native year — see the README's calendar-systems section for why.
+ * Compatibility: since 1.16.0 the string is RFC 9557. Earlier releases wrote the calendar's own
+ * year, month and day (`"5785-01-01[u-ca=hebrew]"` for ISO 2024-10-03), a `;era=` suffix for
+ * `japanese` and `ethiopic`, and the ids `gregorian`, `taiwan`, `islamic-tabular` and
+ * `ethiopic-amete-alem`; those strings are not converted.
  *
  * @param value ISO PlainDate string, optionally calendar-annotated
- * @param calendar target calendar system ("gregorian" | "hebrew" | "islamic-civil" |
- *   "islamic-tabular" | "islamic-umalqura" | "japanese" | "buddhist" | "taiwan" |
- *   "persian" | "indian" | "ethiopic" | "ethiopic-amete-alem" | "coptic")
- * @returns calendar-native ISO-shaped PlainDate string, or "" on invalid input
+ * @param calendar target calendar id ("iso8601" | "gregory" | "hebrew" | "islamic-civil" |
+ *   "islamic-tbla" | "islamic-umalqura" | "japanese" | "buddhist" | "roc" | "persian" |
+ *   "indian" | "ethiopic" | "ethioaa" | "coptic")
+ * @returns RFC 9557 PlainDate string, or "" on invalid input
  *
- * @example convertDateToCalendar("2024-10-03", "hebrew") // "5785-01-01[u-ca=hebrew]"
- * @example convertDateToCalendar("5785-01-01[u-ca=hebrew]", "gregorian") // "2024-10-03"
- * @example convertDateToCalendar("2024-10-03", "gregorian") // "2024-10-03"
- * @example convertDateToCalendar("2024-10-03", "islamic-umalqura") // "1446-03-30[u-ca=islamic-umalqura]"
- * @example convertDateToCalendar("2024-10-03", "japanese") // "0006-10-03[u-ca=japanese;era=reiwa]"
- * @example convertDateToCalendar("2024-10-03", "buddhist") // "2567-10-03[u-ca=buddhist]"
- * @example convertDateToCalendar("2024-10-03", "taiwan") // "0113-10-03[u-ca=taiwan]"
- * @example convertDateToCalendar("2024-10-03", "persian") // "1403-07-12[u-ca=persian]"
- * @example convertDateToCalendar("2024-10-03", "indian") // "1946-07-11[u-ca=indian]"
- * @example convertDateToCalendar("2024-10-03", "ethiopic") // "2017-01-23[u-ca=ethiopic;era=ethiopic]"
- * @example convertDateToCalendar("2024-10-03", "ethiopic-amete-alem") // "7517-01-23[u-ca=ethiopic-amete-alem]"
- * @example convertDateToCalendar("2024-10-03", "coptic") // "1741-01-23[u-ca=coptic]"
+ * @example convertDateToCalendar("2024-10-03", "hebrew") // "2024-10-03[u-ca=hebrew]"
+ * @example convertDateToCalendar("2024-10-03", "japanese") // "2024-10-03[u-ca=japanese]"
+ * @example convertDateToCalendar("1000-01-01", "roc") // "1000-01-01[u-ca=roc]"
+ * @example convertDateToCalendar("+275760-09-13", "hebrew") // "+275760-09-13[u-ca=hebrew]"
+ * @example convertDateToCalendar("2024-10-03[u-ca=hebrew]", "iso8601") // "2024-10-03"
+ * @example convertDateToCalendar("2024-10-03", "gregory") // "2024-10-03[u-ca=gregory]"
+ * @example convertDateToCalendar("2024-10-03", "ethiopic-amete-alem" as never) // "2024-10-03[u-ca=ethioaa]"
+ * @example convertDateToCalendar("0006-10-03[u-ca=japanese;era=reiwa]", "iso8601") // "" (not RFC 9557)
+ * @example convertDateToCalendar("2024-10-03", "gregorian" as never) // "" (a CLDR alias Temporal does not accept; use "gregory")
+ * @example convertDateToCalendar("2024-10-03", "taiwan" as never) // "" (a CLDR alias Temporal does not accept; use "roc")
  * @example convertDateToCalendar("invalid", "hebrew") // ""
  */
 export declare function convertDateToCalendar(value: string, calendar: CalendarSystem): string;