@northguild/gmt 1.14.2 → 1.16.0

package/dist/plain/interval/validate/isValidDateInterval.js

@@ -8,8 +8,10 @@ import { isValidCalendarDate } from "../../validate/index.js";
  * - Both inputs must be ISO 8601 date strings (e.g. `"2024-01-01"`).
  * - Equal `start === end` is valid.
  * - Invalid input, malformed strings, or leap-second strings return `false`.
- * - Accepts GMT calendar-annotated PlainDate strings — E5 (issue #78). Ordering is
+ * - Accepts RFC 9557 calendar-annotated PlainDate strings — E5 (issue #78). Ordering is
  *   calendar-independent, so `start`/`end` may carry different or no calendar tags (D4).
+ * - Compatibility: since 1.16.0 calendar strings are RFC 9557 (ISO digits, `[u-ca=<id>]`, canonical
+ *   calendar ids); see `isValidCalendarDate`.
  *
  * @param start ISO 8601 date string (interval start), optionally calendar-annotated
  * @param end ISO 8601 date string (interval end), optionally calendar-annotated
@@ -19,7 +21,7 @@ import { isValidCalendarDate } from "../../validate/index.js";
  * @example isValidDateInterval("2024-01-01", "2024-01-01") // true
  * @example isValidDateInterval("2024-12-31", "2024-01-01") // false
  * @example isValidDateInterval("invalid", "2024-12-31") // false
- * @example isValidDateInterval("5785-01-01[u-ca=hebrew]", "2024-12-31") // true (mixed calendars — ordering is calendar-independent)
+ * @example isValidDateInterval("2024-10-03[u-ca=hebrew]", "2024-12-31") // true (mixed calendars — ordering is calendar-independent)
  */
 export function isValidDateInterval(start, end) {
     if (typeof start !== "string" || typeof end !== "string") {

package/dist/plain/interval/validate/isValidDateTimeInterval.d.ts

@@ -5,6 +5,9 @@
  * - Both inputs must be ISO 8601 datetime strings (e.g. `"2024-01-01T10:00:00"`).
  * - Equal `start === end` is valid.
  * - Invalid input, malformed strings, or leap-second strings return `false`.
+ * - Each endpoint must satisfy `isValidDateTime`, so annotations are read as Temporal reads them: a time
+ *   zone annotation (`[Europe/Paris]`), `[u-ca=iso8601]` and an elective annotation (`[foo=bar]`) are
+ *   ignored; an unknown critical annotation (`[!foo=bar]`) and a non-ISO calendar is rejected.
  *
  * @param start ISO 8601 datetime string (interval start)
  * @param end ISO 8601 datetime string (interval end)
@@ -14,5 +17,7 @@
  * @example isValidDateTimeInterval("2024-01-01T10:00:00", "2024-01-01T10:00:00") // true
  * @example isValidDateTimeInterval("2024-12-31T23:59:59", "2024-01-01T10:00:00") // false
  * @example isValidDateTimeInterval("invalid", "2024-12-31T23:59:59") // false
+ * @example isValidDateTimeInterval("2024-01-01T09:00:00[u-ca=iso8601]", "2024-01-01T17:00:00[foo=bar]") // true (annotations ignored)
+ * @example isValidDateTimeInterval("2024-01-01T09:00:00[u-ca=hebrew]", "2024-01-01T17:00:00") // false (non-ISO calendar)
  */
 export declare function isValidDateTimeInterval(start: string, end: string): boolean;

package/dist/plain/interval/validate/isValidDateTimeInterval.js

@@ -1,5 +1,5 @@
 import { Temporal } from "@js-temporal/polyfill";
-import { plainDateTime } from "../../../regex/index.js";
+import { isValidDateTime } from "../../validate/index.js";
 /**
  * Return true if `start` and `end` form a valid datetime interval — both parseable as
  * ISO PlainDateTime strings and `start <= end`.
@@ -7,6 +7,9 @@ import { plainDateTime } from "../../../regex/index.js";
  * - Both inputs must be ISO 8601 datetime strings (e.g. `"2024-01-01T10:00:00"`).
  * - Equal `start === end` is valid.
  * - Invalid input, malformed strings, or leap-second strings return `false`.
+ * - Each endpoint must satisfy `isValidDateTime`, so annotations are read as Temporal reads them: a time
+ *   zone annotation (`[Europe/Paris]`), `[u-ca=iso8601]` and an elective annotation (`[foo=bar]`) are
+ *   ignored; an unknown critical annotation (`[!foo=bar]`) and a non-ISO calendar is rejected.
  *
  * @param start ISO 8601 datetime string (interval start)
  * @param end ISO 8601 datetime string (interval end)
@@ -16,12 +19,14 @@ import { plainDateTime } from "../../../regex/index.js";
  * @example isValidDateTimeInterval("2024-01-01T10:00:00", "2024-01-01T10:00:00") // true
  * @example isValidDateTimeInterval("2024-12-31T23:59:59", "2024-01-01T10:00:00") // false
  * @example isValidDateTimeInterval("invalid", "2024-12-31T23:59:59") // false
+ * @example isValidDateTimeInterval("2024-01-01T09:00:00[u-ca=iso8601]", "2024-01-01T17:00:00[foo=bar]") // true (annotations ignored)
+ * @example isValidDateTimeInterval("2024-01-01T09:00:00[u-ca=hebrew]", "2024-01-01T17:00:00") // false (non-ISO calendar)
  */
 export function isValidDateTimeInterval(start, end) {
     if (typeof start !== "string" || typeof end !== "string") {
         return false;
     }
-    if (!plainDateTime.test(start) || !plainDateTime.test(end)) {
+    if (!isValidDateTime(start) || !isValidDateTime(end)) {
         return false;
     }
     try {

package/dist/plain/interval/validate/isValidTimeInterval.d.ts

@@ -5,6 +5,9 @@
  * - Both inputs must be ISO 8601 time strings (e.g. `"14:30:00"`).
  * - Equal `start === end` is valid.
  * - Invalid input, malformed strings, or leap-second strings return `false`.
+ * - Each endpoint must satisfy `isValidTime`, so annotations are read as Temporal reads them: a time
+ *   zone annotation (`[Europe/Paris]`), `[u-ca=iso8601]` and an elective annotation (`[foo=bar]`) are
+ *   ignored; an unknown critical annotation (`[!foo=bar]`) is rejected.
  *
  * @param start ISO 8601 time string (interval start)
  * @param end ISO 8601 time string (interval end)
@@ -14,5 +17,7 @@
  * @example isValidTimeInterval("12:00:00", "12:00:00") // true
  * @example isValidTimeInterval("17:00:00", "09:00:00") // false
  * @example isValidTimeInterval("invalid", "12:00:00") // false
+ * @example isValidTimeInterval("09:00:00[u-ca=iso8601]", "17:00:00[foo=bar]") // true (annotations ignored)
+ * @example isValidTimeInterval("09:00:00[!foo=bar]", "17:00:00") // false (unknown critical annotation)
  */
 export declare function isValidTimeInterval(start: string, end: string): boolean;

package/dist/plain/interval/validate/isValidTimeInterval.js

@@ -1,5 +1,5 @@
 import { Temporal } from "@js-temporal/polyfill";
-import { plainTime } from "../../../regex/index.js";
+import { isValidTime } from "../../validate/index.js";
 /**
  * Return true if `start` and `end` form a valid time interval — both parseable as
  * ISO PlainTime strings and `start <= end`.
@@ -7,6 +7,9 @@ import { plainTime } from "../../../regex/index.js";
  * - Both inputs must be ISO 8601 time strings (e.g. `"14:30:00"`).
  * - Equal `start === end` is valid.
  * - Invalid input, malformed strings, or leap-second strings return `false`.
+ * - Each endpoint must satisfy `isValidTime`, so annotations are read as Temporal reads them: a time
+ *   zone annotation (`[Europe/Paris]`), `[u-ca=iso8601]` and an elective annotation (`[foo=bar]`) are
+ *   ignored; an unknown critical annotation (`[!foo=bar]`) is rejected.
  *
  * @param start ISO 8601 time string (interval start)
  * @param end ISO 8601 time string (interval end)
@@ -16,31 +19,18 @@ import { plainTime } from "../../../regex/index.js";
  * @example isValidTimeInterval("12:00:00", "12:00:00") // true
  * @example isValidTimeInterval("17:00:00", "09:00:00") // false
  * @example isValidTimeInterval("invalid", "12:00:00") // false
+ * @example isValidTimeInterval("09:00:00[u-ca=iso8601]", "17:00:00[foo=bar]") // true (annotations ignored)
+ * @example isValidTimeInterval("09:00:00[!foo=bar]", "17:00:00") // false (unknown critical annotation)
  */
 export function isValidTimeInterval(start, end) {
     if (typeof start !== "string" || typeof end !== "string") {
         return false;
     }
-    if (!plainTime.test(start) || !plainTime.test(end)) {
+    if (!isValidTime(start) || !isValidTime(end)) {
         return false;
     }
     try {
-        const t1 = Temporal.PlainTime.from(start);
-        const t2 = Temporal.PlainTime.from(end);
-        const isLessThan = t1.hour < t2.hour ||
-            (t1.hour === t2.hour && t1.minute < t2.minute) ||
-            (t1.hour === t2.hour &&
-                t1.minute === t2.minute &&
-                t1.second < t2.second) ||
-            (t1.hour === t2.hour &&
-                t1.minute === t2.minute &&
-                t1.second === t2.second &&
-                t1.millisecond < t2.millisecond);
-        const isEqual = t1.hour === t2.hour &&
-            t1.minute === t2.minute &&
-            t1.second === t2.second &&
-            t1.millisecond === t2.millisecond;
-        return isLessThan || isEqual;
+        return (Temporal.PlainTime.compare(Temporal.PlainTime.from(start), Temporal.PlainTime.from(end)) <= 0);
     }
     catch {
         return false;

package/dist/plain/locale/getLocaleEraNames.d.ts

@@ -9,15 +9,25 @@ import type { LocaleNameStyle } from "./getLocaleMonthNames.js";
  * - If a locale has no distinct BCE/CE era names, both array elements
  *   contain the same string — the function never returns a sentinel for
  *   a valid locale, only for invalid input.
- * - Returns `[]` if `locale` is not a valid BCP 47 tag.
+ * - **A `-u-ca-` subtag in `locale` is ignored.** Both lookups pass `calendar: "gregory"` in the
+ *   options bag, and ECMA-402's `ResolveLocale` ranks an options value above the locale
+ *   extension, so ``getLocaleEraNames("en-US-u-ca-buddhist")`` returns the same
+ *   `["Before Christ", "Anno Domini"]` as ``getLocaleEraNames("en-US")``. That is deliberate — the function is Gregorian by
+ *   contract — but it means the tag is accepted and overridden, not rejected. For another
+ *   calendar's names, format a date in it: `formatDate("2024-03-15", "en-US-u-ca-buddhist", { era: "long", year: "numeric" })`.
+ * - Returns `[]` if `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 locale BCP 47 locale tag (e.g. "en-US", "fr-FR", "ar-SA")
+ * @param locale BCP 47 locale tag (e.g. "en-US", "fr-FR", "ar-SA"), 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 []
  * @param style Optional name style: `"long"` (default), `"short"`, or `"narrow"`
  * @returns 2-element `[BCE-label, CE-label]` array, or `[]` on invalid input
  *
  * @example getLocaleEraNames("en-US") // ["Before Christ", "Anno Domini"]
  * @example getLocaleEraNames("de-DE", "short") // ["v. Chr.", "n. Chr."]
  * @example getLocaleEraNames("ja-JP", "narrow") // ["BC", "AD"]
- * @example getLocaleEraNames("not-a-locale") // []
+ * @example getLocaleEraNames("en-US-u-ca-buddhist") // ["Before Christ", "Anno Domini"] (the -u-ca- subtag is overridden)
+ * @example getLocaleEraNames("not-a-locale-!!") // []
+ * @example getLocaleEraNames(["fr-FR", "en-US"]) // ["avant Jésus-Christ", "après Jésus-Christ"]
  */
-export declare function getLocaleEraNames(locale: string, style?: LocaleNameStyle): string[];
+export declare function getLocaleEraNames(locale: string | string[], style?: LocaleNameStyle): string[];

package/dist/plain/locale/getLocaleEraNames.js

@@ -1,4 +1,7 @@
-import { Temporal } from "@js-temporal/polyfill";
+// fallow-ignore-file code-duplication -- sibling variant keeps its own guard, parse and try/catch, by design
+import { resolveRequiredLocale } from "../../internal/resolveLocale.js";
+// Imported from its module, not the `internal` barrel: `internal/patternToken.ts` imports this file.
+import { zonedDateTimeFrom } from "../../internal/zonedWallClock.js";
 /**
  * Return a locale's Gregorian era names as [BCE-label, CE-label].
  *
@@ -9,58 +12,70 @@ import { Temporal } from "@js-temporal/polyfill";
  * - If a locale has no distinct BCE/CE era names, both array elements
  *   contain the same string — the function never returns a sentinel for
  *   a valid locale, only for invalid input.
- * - Returns `[]` if `locale` is not a valid BCP 47 tag.
+ * - **A `-u-ca-` subtag in `locale` is ignored.** Both lookups pass `calendar: "gregory"` in the
+ *   options bag, and ECMA-402's `ResolveLocale` ranks an options value above the locale
+ *   extension, so ``getLocaleEraNames("en-US-u-ca-buddhist")`` returns the same
+ *   `["Before Christ", "Anno Domini"]` as ``getLocaleEraNames("en-US")``. That is deliberate — the function is Gregorian by
+ *   contract — but it means the tag is accepted and overridden, not rejected. For another
+ *   calendar's names, format a date in it: `formatDate("2024-03-15", "en-US-u-ca-buddhist", { era: "long", year: "numeric" })`.
+ * - Returns `[]` if `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 locale BCP 47 locale tag (e.g. "en-US", "fr-FR", "ar-SA")
+ * @param locale BCP 47 locale tag (e.g. "en-US", "fr-FR", "ar-SA"), 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 []
  * @param style Optional name style: `"long"` (default), `"short"`, or `"narrow"`
  * @returns 2-element `[BCE-label, CE-label]` array, or `[]` on invalid input
  *
  * @example getLocaleEraNames("en-US") // ["Before Christ", "Anno Domini"]
  * @example getLocaleEraNames("de-DE", "short") // ["v. Chr.", "n. Chr."]
  * @example getLocaleEraNames("ja-JP", "narrow") // ["BC", "AD"]
- * @example getLocaleEraNames("not-a-locale") // []
+ * @example getLocaleEraNames("en-US-u-ca-buddhist") // ["Before Christ", "Anno Domini"] (the -u-ca- subtag is overridden)
+ * @example getLocaleEraNames("not-a-locale-!!") // []
+ * @example getLocaleEraNames(["fr-FR", "en-US"]) // ["avant Jésus-Christ", "après Jésus-Christ"]
  */
 export function getLocaleEraNames(locale, style = "long") {
-    if (typeof locale !== "string")
-        return [];
-    try {
-        new Intl.Locale(locale);
-    }
-    catch {
-        return [];
-    }
     try {
-        const resolved = style === "short" || style === "narrow" ? style : "long";
-        const formatter = new Intl.DateTimeFormat(locale, {
-            calendar: "gregory",
-            era: resolved,
-            timeZone: "UTC",
-        });
-        // Year 1 BC (proleptic Gregorian) — Temporal represents 1 BC as year 0.
-        const bceInstant = Temporal.ZonedDateTime.from({
-            year: 0,
-            month: 1,
-            day: 1,
-            hour: 12,
-            timeZone: "UTC",
-            calendar: "gregory",
-        }).toInstant();
-        // Year 1 AD (proleptic Gregorian).
-        const ceInstant = Temporal.ZonedDateTime.from({
-            year: 1,
-            month: 1,
-            day: 1,
-            hour: 12,
-            timeZone: "UTC",
-            calendar: "gregory",
-        }).toInstant();
-        const bceParts = formatter.formatToParts(bceInstant.epochMilliseconds);
-        const bceEra = bceParts.find((part) => part.type === "era")?.value ?? "";
-        const ceParts = formatter.formatToParts(ceInstant.epochMilliseconds);
-        const ceEra = ceParts.find((part) => part.type === "era")?.value ?? "";
-        return [bceEra, ceEra];
+        const resolvedLocale = resolveRequiredLocale(locale);
+        if (resolvedLocale === null)
+            return [];
+        try {
+            const resolved = style === "short" || style === "narrow" ? style : "long";
+            const formatter = new Intl.DateTimeFormat(resolvedLocale, {
+                calendar: "gregory",
+                era: resolved,
+                timeZone: "UTC",
+            });
+            // Year 1 BC (proleptic Gregorian) — Temporal represents 1 BC as year 0.
+            const bceInstant = zonedDateTimeFrom({
+                year: 0,
+                month: 1,
+                day: 1,
+                hour: 12,
+                timeZone: "UTC",
+                calendar: "gregory",
+            }).toInstant();
+            // Year 1 AD (proleptic Gregorian).
+            const ceInstant = zonedDateTimeFrom({
+                year: 1,
+                month: 1,
+                day: 1,
+                hour: 12,
+                timeZone: "UTC",
+                calendar: "gregory",
+            }).toInstant();
+            const bceParts = formatter.formatToParts(bceInstant.epochMilliseconds);
+            const bceEra = bceParts.find((part) => part.type === "era")?.value ?? "";
+            const ceParts = formatter.formatToParts(ceInstant.epochMilliseconds);
+            const ceEra = ceParts.find((part) => part.type === "era")?.value ?? "";
+            return [bceEra, ceEra];
+        }
+        catch {
+            return [];
+        }
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return [];
     }
 }

package/dist/plain/locale/getLocaleMeridiems.d.ts

@@ -6,14 +6,17 @@
  *   `ar-SA` → `["ص", "م"]`.
  * - Uses the host runtime's `Intl` data via `Intl.DateTimeFormat`, so output
  *   depends on the runtime's ICU build.
- * - Returns `[]` if `locale` is not a valid BCP 47 tag.
+ * - Returns `[]` if `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 locale BCP 47 locale tag (e.g. "en-US", "fr-FR", "ar-SA")
+ * @param locale BCP 47 locale tag (e.g. "en-US", "fr-FR", "ar-SA"), 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 []
  * @returns 2-element `[AM-label, PM-label]` array, or `[]` on invalid input
  *
  * @example getLocaleMeridiems("en-US") // ["AM", "PM"]
  * @example getLocaleMeridiems("en-GB") // ["am", "pm"]
  * @example getLocaleMeridiems("zh-CN") // ["上午", "下午"]
- * @example getLocaleMeridiems("not-a-locale") // []
+ * @example getLocaleMeridiems("not-a-locale-!!") // []
+ * @example getLocaleMeridiems(["ja-JP", "en-US"]) // ["午前", "午後"]
  */
-export declare function getLocaleMeridiems(locale: string): string[];
+export declare function getLocaleMeridiems(locale: string | string[]): string[];

package/dist/plain/locale/getLocaleMeridiems.js

@@ -1,3 +1,4 @@
+import { resolveRequiredLocale } from "../../internal/resolveLocale.js";
 /**
  * Return a locale's AM/PM (day-period) labels as `[AM-label, PM-label]`.
  *
@@ -6,39 +7,44 @@
  *   `ar-SA` → `["ص", "م"]`.
  * - Uses the host runtime's `Intl` data via `Intl.DateTimeFormat`, so output
  *   depends on the runtime's ICU build.
- * - Returns `[]` if `locale` is not a valid BCP 47 tag.
+ * - Returns `[]` if `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 locale BCP 47 locale tag (e.g. "en-US", "fr-FR", "ar-SA")
+ * @param locale BCP 47 locale tag (e.g. "en-US", "fr-FR", "ar-SA"), 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 []
  * @returns 2-element `[AM-label, PM-label]` array, or `[]` on invalid input
  *
  * @example getLocaleMeridiems("en-US") // ["AM", "PM"]
  * @example getLocaleMeridiems("en-GB") // ["am", "pm"]
  * @example getLocaleMeridiems("zh-CN") // ["上午", "下午"]
- * @example getLocaleMeridiems("not-a-locale") // []
+ * @example getLocaleMeridiems("not-a-locale-!!") // []
+ * @example getLocaleMeridiems(["ja-JP", "en-US"]) // ["午前", "午後"]
  */
 export function getLocaleMeridiems(locale) {
-    if (typeof locale !== "string")
-        return [];
-    try {
-        new Intl.Locale(locale);
-    }
-    catch {
-        return [];
-    }
     try {
-        const formatter = new Intl.DateTimeFormat(locale, {
-            timeZone: "UTC",
-            hour: "numeric",
-            hour12: true,
-        });
-        const am = formatter.formatToParts(0).find((part) => part.type === "dayPeriod")
-            ?.value ?? "";
-        const pm = formatter
-            .formatToParts(12 * 60 * 60 * 1000)
-            .find((part) => part.type === "dayPeriod")?.value ?? "";
-        return [am, pm];
+        const resolvedLocale = resolveRequiredLocale(locale);
+        if (resolvedLocale === null)
+            return [];
+        try {
+            const formatter = new Intl.DateTimeFormat(resolvedLocale, {
+                timeZone: "UTC",
+                hour: "numeric",
+                hour12: true,
+            });
+            const am = formatter.formatToParts(0).find((part) => part.type === "dayPeriod")
+                ?.value ?? "";
+            const pm = formatter
+                .formatToParts(12 * 60 * 60 * 1000)
+                .find((part) => part.type === "dayPeriod")?.value ?? "";
+            return [am, pm];
+        }
+        catch {
+            return [];
+        }
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return [];
     }
 }

package/dist/plain/locale/getLocaleMonthNames.d.ts

@@ -14,15 +14,25 @@ export type LocaleNameStyle = "long" | "short" | "narrow";
  *   locale; partial-ICU runtimes fall back to English).
  * - Restricted to the Gregorian calendar; non-Gregorian calendar variants
  *   are out of scope for this function.
- * - Returns `[]` if `locale` is not a valid BCP 47 tag.
+ * - **A `-u-ca-` subtag in `locale` is ignored.** Both lookups pass `calendar: "gregory"` in the
+ *   options bag, and ECMA-402's `ResolveLocale` ranks an options value above the locale
+ *   extension, so ``getLocaleMonthNames("en-US-u-ca-hebrew")`` returns the same
+ *   twelve Gregorian month names as ``getLocaleMonthNames("en-US")``. That is deliberate — the function is Gregorian by
+ *   contract — but it means the tag is accepted and overridden, not rejected. For another
+ *   calendar's names, format a date in it: `formatDate("2024-03-15", "en-US-u-ca-hebrew", { month: "long" })`.
+ * - Returns `[]` if `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 locale BCP 47 locale tag (e.g. "en-US", "fr-FR", "ar-SA")
+ * @param locale BCP 47 locale tag (e.g. "en-US", "fr-FR", "ar-SA"), 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 []
  * @param style Optional name style: `"long"` (default), `"short"`, or `"narrow"`
  * @returns 12-element array of month names in calendar order, or `[]` on invalid input
  *
  * @example getLocaleMonthNames("en-US") // ["January", "February", ... "December"]
  * @example getLocaleMonthNames("de-DE", "short") // ["Jan", "Feb", "Mär", ... "Dez"]
  * @example getLocaleMonthNames("fr-FR", "narrow") // ["J", "F", "M", ... "D"]
- * @example getLocaleMonthNames("not-a-locale") // []
+ * @example getLocaleMonthNames("en-US-u-ca-hebrew") // ["January", "February", ... "December"] (the -u-ca- subtag is overridden)
+ * @example getLocaleMonthNames("not-a-locale-!!") // []
+ * @example getLocaleMonthNames(["fr-FR", "en-US"]) // ["janvier", "février", …, "décembre"]
  */
-export declare function getLocaleMonthNames(locale: string, style?: LocaleNameStyle): string[];
+export declare function getLocaleMonthNames(locale: string | string[], style?: LocaleNameStyle): string[];

package/dist/plain/locale/getLocaleMonthNames.js

@@ -1,3 +1,5 @@
+// fallow-ignore-file code-duplication -- sibling variant keeps its own guard, parse and try/catch, by design
+import { resolveRequiredLocale } from "../../internal/resolveLocale.js";
 import { Temporal } from "@js-temporal/polyfill";
 /**
  * Return the 12 Gregorian calendar-month names for a locale, in calendar
@@ -8,38 +10,51 @@ import { Temporal } from "@js-temporal/polyfill";
  *   locale; partial-ICU runtimes fall back to English).
  * - Restricted to the Gregorian calendar; non-Gregorian calendar variants
  *   are out of scope for this function.
- * - Returns `[]` if `locale` is not a valid BCP 47 tag.
+ * - **A `-u-ca-` subtag in `locale` is ignored.** Both lookups pass `calendar: "gregory"` in the
+ *   options bag, and ECMA-402's `ResolveLocale` ranks an options value above the locale
+ *   extension, so ``getLocaleMonthNames("en-US-u-ca-hebrew")`` returns the same
+ *   twelve Gregorian month names as ``getLocaleMonthNames("en-US")``. That is deliberate — the function is Gregorian by
+ *   contract — but it means the tag is accepted and overridden, not rejected. For another
+ *   calendar's names, format a date in it: `formatDate("2024-03-15", "en-US-u-ca-hebrew", { month: "long" })`.
+ * - Returns `[]` if `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 locale BCP 47 locale tag (e.g. "en-US", "fr-FR", "ar-SA")
+ * @param locale BCP 47 locale tag (e.g. "en-US", "fr-FR", "ar-SA"), 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 []
  * @param style Optional name style: `"long"` (default), `"short"`, or `"narrow"`
  * @returns 12-element array of month names in calendar order, or `[]` on invalid input
  *
  * @example getLocaleMonthNames("en-US") // ["January", "February", ... "December"]
  * @example getLocaleMonthNames("de-DE", "short") // ["Jan", "Feb", "Mär", ... "Dez"]
  * @example getLocaleMonthNames("fr-FR", "narrow") // ["J", "F", "M", ... "D"]
- * @example getLocaleMonthNames("not-a-locale") // []
+ * @example getLocaleMonthNames("en-US-u-ca-hebrew") // ["January", "February", ... "December"] (the -u-ca- subtag is overridden)
+ * @example getLocaleMonthNames("not-a-locale-!!") // []
+ * @example getLocaleMonthNames(["fr-FR", "en-US"]) // ["janvier", "février", …, "décembre"]
  */
 export function getLocaleMonthNames(locale, style = "long") {
-    if (typeof locale !== "string")
-        return [];
     try {
-        // Validate the BCP 47 tag; `Intl.Locale` throws on a syntactically
-        // invalid tag, which we map to the array sentinel.
-        new Intl.Locale(locale);
-    }
-    catch {
-        return [];
-    }
-    try {
-        const resolved = style === "short" || style === "narrow" ? style : "long";
-        const names = [];
-        for (let month = 1; month <= 12; month++) {
-            const date = Temporal.PlainDate.from(`2024-${String(month).padStart(2, "0")}-15`);
-            names.push(date.toLocaleString(locale, { month: resolved, calendar: "gregory" }));
+        const resolvedLocale = resolveRequiredLocale(locale);
+        if (resolvedLocale === null)
+            return [];
+        try {
+            const resolved = style === "short" || style === "narrow" ? style : "long";
+            const names = [];
+            for (let month = 1; month <= 12; month++) {
+                const date = Temporal.PlainDate.from(`2024-${String(month).padStart(2, "0")}-15`);
+                names.push(date.toLocaleString(resolvedLocale, {
+                    month: resolved,
+                    calendar: "gregory",
+                }));
+            }
+            return names;
+        }
+        catch {
+            return [];
         }
-        return names;
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return [];
     }
 }

package/dist/plain/locale/getLocaleWeekdayNames.d.ts

@@ -3,23 +3,30 @@ import type { LocaleNameStyle } from "./getLocaleMonthNames.js";
  * Return the 7 weekday names for a locale, ordered starting from the
  * locale's first day of the week.
  *
- * - For `en-US` the array starts with Sunday; for `fr-FR` it starts with
- *   Monday; for `ar-SA` it starts with Saturday — matching GMT's existing
- *   locale-first-day convention in `getLocaleDayOfWeek` / `getLocaleStartOfWeek`.
+ * - The order is the locale's **first day of the week**, never its weekend. For `en-US` and
+ *   `ar-SA` the array starts with Sunday, for `fr-FR` with Monday, for `ar-EG` with Saturday —
+ *   matching GMT's existing locale-first-day convention in `getLocaleDayOfWeek` /
+ *   `getLocaleStartOfWeek`. `ar-SA`'s weekend is Friday and Saturday
+ *   (`new Intl.Locale("ar-SA").getWeekInfo()` is `{ firstDay: 7, weekend: [5, 6] }`), but its week
+ *   still begins on Sunday; a locale's weekend says nothing about where its week starts.
  * - This ordering is consistent with `getLocaleDayOfWeek`: for any valid
  *   date, `getLocaleWeekdayNames(locale)[getLocaleDayOfWeek(date, locale)]`
  *   is that date's localized weekday name.
  * - Uses the host runtime's `Intl` data via `Temporal.PlainDate`, so output
  *   depends on the runtime's ICU build.
- * - Returns `[]` if `locale` is not a valid BCP 47 tag.
+ * - Returns `[]` if `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 locale BCP 47 locale tag (e.g. "en-US", "fr-FR", "ar-SA")
+ * @param locale BCP 47 locale tag (e.g. "en-US", "fr-FR", "ar-SA"), 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 []
  * @param style Optional name style: `"long"` (default), `"short"`, or `"narrow"`
  * @returns 7-element array of weekday names from the locale's first day, or `[]` on invalid input
  *
  * @example getLocaleWeekdayNames("en-US") // ["Sunday", "Monday", ... "Saturday"]
  * @example getLocaleWeekdayNames("fr-FR") // ["lundi", "mardi", ... "dimanche"]
  * @example getLocaleWeekdayNames("de-DE", "short") // ["Mo", "Di", "Mi", ... "So"]
- * @example getLocaleWeekdayNames("not-a-locale") // []
+ * @example getLocaleWeekdayNames("ar-EG")[0] // "السبت" (Saturday — ar-EG's first day, unlike ar-SA's Sunday)
+ * @example getLocaleWeekdayNames("not-a-locale-!!") // []
+ * @example getLocaleWeekdayNames(["fr-FR", "en-US"]) // ["lundi", "mardi", …, "dimanche"]
  */
-export declare function getLocaleWeekdayNames(locale: string, style?: LocaleNameStyle): string[];
+export declare function getLocaleWeekdayNames(locale: string | string[], style?: LocaleNameStyle): string[];