@northguild/gmt 1.14.2 → 1.16.0

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

@@ -1,16 +1,23 @@
+import type { Temporal } from "@js-temporal/polyfill";
 import type { TimeDurationUnit } from "../../types/index.js";
 /**
  * Return the largest TimeDurationUnit from the provided array.
  *
  * - Returns the largest unit based on Temporal's unit order: hours > minutes > seconds > milliseconds > microseconds > nanoseconds.
- * - Defaults to "seconds" if no valid unit is found in the array.
+ * - Each unit may be singular or plural (`"day"` or `"days"`), as Temporal accepts; the result is
+ *   the plural name.
+ * - Returns "" when `units` is not an array, is empty, or holds anything that is not a unit of
+ *   this family.
+ * - **Compatibility:** before 1.16.0 an empty or invalid `units` returned a default unit
+ *   (`"seconds"`).
  *
- * @param units array of TimeDurationUnits to evaluate
- * @returns the largest TimeDurationUnit found in the array, or "seconds" if none are valid
+ * @param units array of TimeDurationUnits (singular or plural names) to evaluate
+ * @returns the largest TimeDurationUnit found in the array, or "" on invalid input
  *
  * @example getLargestTimeDurationUnit(["minutes", "seconds"]) // "minutes"
  * @example getLargestTimeDurationUnit(["seconds", "milliseconds"]) // "seconds"
- * @example getLargestTimeDurationUnit(["milliseconds", "microseconds"]) // "milliseconds"
- * @example getLargestTimeDurationUnit([]) // "seconds"
+ * @example getLargestTimeDurationUnit(["second", "minute"]) // "minutes" (singular names count as their plural)
+ * @example getLargestTimeDurationUnit([]) // "" (no unit to choose from)
+ * @example getLargestTimeDurationUnit(["seconds", "fortnights"]) // "" (an invalid unit)
  */
-export declare function getLargestTimeDurationUnit(units: TimeDurationUnit[]): TimeDurationUnit;
+export declare function getLargestTimeDurationUnit(units: Array<TimeDurationUnit | Temporal.TimeUnit>): TimeDurationUnit | "";

package/dist/plain/calculate/getLargestTimeDurationUnit.js

@@ -1,31 +1,46 @@
+import { resolveDurationUnit } from "../../internal/resolveDurationUnit.js";
+import { isValidTimeDurationUnit } from "../validate/isValidTimeDurationUnit.js";
+const ORDER = [
+    "hours",
+    "minutes",
+    "seconds",
+    "milliseconds",
+    "microseconds",
+    "nanoseconds",
+];
 /**
  * Return the largest TimeDurationUnit from the provided array.
  *
  * - Returns the largest unit based on Temporal's unit order: hours > minutes > seconds > milliseconds > microseconds > nanoseconds.
- * - Defaults to "seconds" if no valid unit is found in the array.
+ * - Each unit may be singular or plural (`"day"` or `"days"`), as Temporal accepts; the result is
+ *   the plural name.
+ * - Returns "" when `units` is not an array, is empty, or holds anything that is not a unit of
+ *   this family.
+ * - **Compatibility:** before 1.16.0 an empty or invalid `units` returned a default unit
+ *   (`"seconds"`).
  *
- * @param units array of TimeDurationUnits to evaluate
- * @returns the largest TimeDurationUnit found in the array, or "seconds" if none are valid
+ * @param units array of TimeDurationUnits (singular or plural names) to evaluate
+ * @returns the largest TimeDurationUnit found in the array, or "" on invalid input
  *
  * @example getLargestTimeDurationUnit(["minutes", "seconds"]) // "minutes"
  * @example getLargestTimeDurationUnit(["seconds", "milliseconds"]) // "seconds"
- * @example getLargestTimeDurationUnit(["milliseconds", "microseconds"]) // "milliseconds"
- * @example getLargestTimeDurationUnit([]) // "seconds"
+ * @example getLargestTimeDurationUnit(["second", "minute"]) // "minutes" (singular names count as their plural)
+ * @example getLargestTimeDurationUnit([]) // "" (no unit to choose from)
+ * @example getLargestTimeDurationUnit(["seconds", "fortnights"]) // "" (an invalid unit)
  */
 export function getLargestTimeDurationUnit(units) {
-    const order = [
-        "hours",
-        "minutes",
-        "seconds",
-        "milliseconds",
-        "microseconds",
-        "nanoseconds",
-    ];
-    for (const unit of order) {
-        if (units.includes(unit)) {
-            return unit;
+    try {
+        if (!Array.isArray(units) || units.length === 0)
+            return "";
+        const plurals = units.map((unit) => resolveDurationUnit(unit));
+        if (!plurals.every((unit) => typeof unit === "string" && isValidTimeDurationUnit(unit))) {
+            return "";
         }
+        return ORDER.find((unit) => plurals.includes(unit)) ?? "";
+    }
+    catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
+        return "";
     }
-    // Default to seconds if no valid unit found, though this case should be prevented by validation
-    return "seconds";
 }

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

@@ -5,16 +5,20 @@
  * - Resolves the locale's first day of week via `Intl.Locale.prototype.weekInfo`.
  * - Falls back to Monday if the runtime's `weekInfo` data doesn't resolve
  *   a first day for the locale.
- * - Returns `null` if `value` is not a valid ISO date or `locale` is unresolvable.
+ * - Returns `null` if `value` is not a valid ISO date 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 8601 date string
- * @param locale BCP 47 locale tag (e.g. "en-US", "fr-FR")
+ * @param locale BCP 47 locale tag (e.g. "en-US", "fr-FR"), 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 null
  * @returns locale-relative day-of-week index (0–6) or null on invalid input
  *
  * @example getLocaleDayOfWeek("2024-02-25", "en-US") // 0 (Sunday)
  * @example getLocaleDayOfWeek("2024-02-26", "en-US") // 1 (Monday)
  * @example getLocaleDayOfWeek("2024-02-26", "fr-FR") // 0 (Monday)
  * @example getLocaleDayOfWeek("invalid-date", "en-US") // null
- * @example getLocaleDayOfWeek("2024-02-29", "not-a-locale") // null
+ * @example getLocaleDayOfWeek("2024-02-29", "not-a-locale-!!") // null
+ * @example getLocaleDayOfWeek("2024-05-15", ["en-US", "fr-FR"]) // 3 (Wednesday in a Sunday-first week)
  */
-export declare function getLocaleDayOfWeek(value: string, locale: string): number | null;
+export declare function getLocaleDayOfWeek(value: string, locale: string | string[]): number | null;

package/dist/plain/calculate/getLocaleDayOfWeek.js

@@ -1,3 +1,4 @@
+// fallow-ignore-file code-duplication -- sibling variant keeps its own guard, parse and try/catch, by design
 import { Temporal } from "@js-temporal/polyfill";
 import { getLocaleFirstDayOfWeek } from "../../internal/index.js";
 import { isValidDate } from "../validate/index.js";
@@ -8,17 +9,21 @@ import { isValidDate } from "../validate/index.js";
  * - Resolves the locale's first day of week via `Intl.Locale.prototype.weekInfo`.
  * - Falls back to Monday if the runtime's `weekInfo` data doesn't resolve
  *   a first day for the locale.
- * - Returns `null` if `value` is not a valid ISO date or `locale` is unresolvable.
+ * - Returns `null` if `value` is not a valid ISO date 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 8601 date string
- * @param locale BCP 47 locale tag (e.g. "en-US", "fr-FR")
+ * @param locale BCP 47 locale tag (e.g. "en-US", "fr-FR"), 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 null
  * @returns locale-relative day-of-week index (0–6) or null on invalid input
  *
  * @example getLocaleDayOfWeek("2024-02-25", "en-US") // 0 (Sunday)
  * @example getLocaleDayOfWeek("2024-02-26", "en-US") // 1 (Monday)
  * @example getLocaleDayOfWeek("2024-02-26", "fr-FR") // 0 (Monday)
  * @example getLocaleDayOfWeek("invalid-date", "en-US") // null
- * @example getLocaleDayOfWeek("2024-02-29", "not-a-locale") // null
+ * @example getLocaleDayOfWeek("2024-02-29", "not-a-locale-!!") // null
+ * @example getLocaleDayOfWeek("2024-05-15", ["en-US", "fr-FR"]) // 3 (Wednesday in a Sunday-first week)
  */
 export function getLocaleDayOfWeek(value, locale) {
     if (!isValidDate(value))

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

@@ -9,15 +9,19 @@
  * - Distinct from `endOfDate(value, "week", { weekStartsOn })`, which
  *   takes an explicit ISO-biased `weekStartsOn` option instead of deriving
  *   it from a locale.
- * - Returns "" if `value` or `locale` is invalid.
+ * - Returns "" 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 8601 date string
- * @param locale BCP 47 locale tag (e.g. "en-US", "fr-FR")
+ * @param locale BCP 47 locale tag (e.g. "en-US", "fr-FR"), 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 ISO 8601 date string for the end of `value`'s locale-relative week, or "" on invalid input
  *
  * @example getLocaleEndOfWeek("2024-02-29", "en-US") // "2024-03-02" (Saturday)
  * @example getLocaleEndOfWeek("2024-02-29", "fr-FR") // "2024-03-03" (Sunday)
  * @example getLocaleEndOfWeek("invalid-date", "en-US") // ""
- * @example getLocaleEndOfWeek("2024-02-29", "not-a-locale") // ""
+ * @example getLocaleEndOfWeek("2024-02-29", "not-a-locale-!!") // ""
+ * @example getLocaleEndOfWeek("2024-05-15", ["fr-FR", "en-US"]) // "2024-05-19"
  */
-export declare function getLocaleEndOfWeek(value: string, locale: string): string;
+export declare function getLocaleEndOfWeek(value: string, locale: string | string[]): string;

package/dist/plain/calculate/getLocaleEndOfWeek.js

@@ -1,3 +1,4 @@
+// fallow-ignore-file code-duplication -- sibling variant keeps its own guard, parse and try/catch, by design
 import { Temporal } from "@js-temporal/polyfill";
 import { getLocaleFirstDayOfWeek } from "../../internal/index.js";
 import { isValidDate } from "../validate/index.js";
@@ -12,16 +13,20 @@ import { isValidDate } from "../validate/index.js";
  * - Distinct from `endOfDate(value, "week", { weekStartsOn })`, which
  *   takes an explicit ISO-biased `weekStartsOn` option instead of deriving
  *   it from a locale.
- * - Returns "" if `value` or `locale` is invalid.
+ * - Returns "" 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 8601 date string
- * @param locale BCP 47 locale tag (e.g. "en-US", "fr-FR")
+ * @param locale BCP 47 locale tag (e.g. "en-US", "fr-FR"), 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 ISO 8601 date string for the end of `value`'s locale-relative week, or "" on invalid input
  *
  * @example getLocaleEndOfWeek("2024-02-29", "en-US") // "2024-03-02" (Saturday)
  * @example getLocaleEndOfWeek("2024-02-29", "fr-FR") // "2024-03-03" (Sunday)
  * @example getLocaleEndOfWeek("invalid-date", "en-US") // ""
- * @example getLocaleEndOfWeek("2024-02-29", "not-a-locale") // ""
+ * @example getLocaleEndOfWeek("2024-02-29", "not-a-locale-!!") // ""
+ * @example getLocaleEndOfWeek("2024-05-15", ["fr-FR", "en-US"]) // "2024-05-19"
  */
 export function getLocaleEndOfWeek(value, locale) {
     if (!isValidDate(value))

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

@@ -9,15 +9,19 @@
  * - Distinct from `startOfDate(value, "week", { weekStartsOn })`, which
  *   takes an explicit ISO-biased `weekStartsOn` option instead of deriving
  *   it from a locale.
- * - Returns "" if `value` or `locale` is invalid.
+ * - Returns "" 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 8601 date string
- * @param locale BCP 47 locale tag (e.g. "en-US", "fr-FR")
+ * @param locale BCP 47 locale tag (e.g. "en-US", "fr-FR"), 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 ISO 8601 date string for the start of `value`'s locale-relative week, or "" on invalid input
  *
  * @example getLocaleStartOfWeek("2024-02-29", "en-US") // "2024-02-25" (Sunday)
  * @example getLocaleStartOfWeek("2024-02-29", "fr-FR") // "2024-02-26" (Monday)
  * @example getLocaleStartOfWeek("invalid-date", "en-US") // ""
- * @example getLocaleStartOfWeek("2024-02-29", "not-a-locale") // ""
+ * @example getLocaleStartOfWeek("2024-02-29", "not-a-locale-!!") // ""
+ * @example getLocaleStartOfWeek("2024-05-15", ["en-US", "fr-FR"]) // "2024-05-12" (en-US, the first listed locale, starts weeks on Sunday)
  */
-export declare function getLocaleStartOfWeek(value: string, locale: string): string;
+export declare function getLocaleStartOfWeek(value: string, locale: string | string[]): string;

package/dist/plain/calculate/getLocaleStartOfWeek.js

@@ -1,3 +1,4 @@
+// fallow-ignore-file code-duplication -- sibling variant keeps its own guard, parse and try/catch, by design
 import { Temporal } from "@js-temporal/polyfill";
 import { getLocaleFirstDayOfWeek } from "../../internal/index.js";
 import { isValidDate } from "../validate/index.js";
@@ -12,16 +13,20 @@ import { isValidDate } from "../validate/index.js";
  * - Distinct from `startOfDate(value, "week", { weekStartsOn })`, which
  *   takes an explicit ISO-biased `weekStartsOn` option instead of deriving
  *   it from a locale.
- * - Returns "" if `value` or `locale` is invalid.
+ * - Returns "" 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 8601 date string
- * @param locale BCP 47 locale tag (e.g. "en-US", "fr-FR")
+ * @param locale BCP 47 locale tag (e.g. "en-US", "fr-FR"), 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 ISO 8601 date string for the start of `value`'s locale-relative week, or "" on invalid input
  *
  * @example getLocaleStartOfWeek("2024-02-29", "en-US") // "2024-02-25" (Sunday)
  * @example getLocaleStartOfWeek("2024-02-29", "fr-FR") // "2024-02-26" (Monday)
  * @example getLocaleStartOfWeek("invalid-date", "en-US") // ""
- * @example getLocaleStartOfWeek("2024-02-29", "not-a-locale") // ""
+ * @example getLocaleStartOfWeek("2024-02-29", "not-a-locale-!!") // ""
+ * @example getLocaleStartOfWeek("2024-05-15", ["en-US", "fr-FR"]) // "2024-05-12" (en-US, the first listed locale, starts weeks on Sunday)
  */
 export function getLocaleStartOfWeek(value, locale) {
     if (!isValidDate(value))

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

@@ -1,28 +1,38 @@
 /**
- * Return the locale-relative week-numbering year `value` belongs to,
- * using `locale`'s first day of week and minimal-days-in-first-week
- * (e.g. en-US: week 1 always contains Jan 1; ISO/most European locales:
- * week 1 always contains Jan 4).
+ * Return the locale-relative week-numbering year `value` belongs to, from `locale`'s first day of
+ * week and a minimal-days-in-first-week rule.
  *
- * - Distinct from `value`'s calendar year, for the same reason
- *   `getWeekYear` is — late-December/early-January dates can belong to a
- *   different week-year than their calendar year, and the boundary
- *   depends on the locale's week-numbering rule.
- * - Distinct from `getWeekYear`: this uses the locale's first day of
- *   week and minimal-days rule (via `Intl.Locale.prototype.weekInfo`)
- *   instead of the fixed ISO rule (Monday-start, 4 minimal days) — the
- *   two can disagree on the same date near a year boundary.
- * - Resolves `locale`'s week-numbering rule via
- *   `Intl.Locale.prototype.weekInfo`.
- * - Returns null if `value` or `locale` is invalid.
+ * - Distinct from `value`'s calendar year, for the same reason `getWeekYear` is: late-December and
+ *   early-January dates can belong to a neighbouring week-year.
+ * - Week 1 is the week starting on `locale`'s first day of week that holds at least `minimalDays`
+ *   days of January (UTS #35 Part 4, Week Data). The first day of week comes from
+ *   `Intl.Locale.prototype.getWeekInfo`.
+ * - **`minimalDays` defaults to `4`, the ISO 8601 rule, on every runtime.** ECMA-402 does not expose
+ *   a locale's minimal days: Intl Locale Info returns only `firstDay` and `weekend`
+ *   (tc39/proposal-intl-locale-info#86), so older runtimes that still reported it disagreed with
+ *   newer ones about the same date. Pass CLDR's value when you need a locale's own rule: in CLDR 48
+ *   `weekData`, the world default (`001`) is `1` — week 1 always contains January 1, as in `US`,
+ *   `CA`, `MX`, `JP` and `CN` — and `4` is set for a list of mostly European regions such as `GB`,
+ *   `DE` and `FR`, where it matches this default.
+ * - Returns null if `value` or `locale` is invalid, or if `minimalDays` is not an integer from 1 to 7.
+ * - **Compatibility:** before 1.16.0 the default read the runtime's `minimalDays` where one was
+ *   exposed (Node 22), so a locale such as `en-US` got `1` there and `4` on Node 24 and later. Pass
+ *   `{ minimalDays: 1 }` to keep the Node 22 result for such a locale on every runtime.
  *
  * @param value ISO PlainDate string
- * @param locale BCP 47 locale tag (e.g. "en-US", "fr-FR")
+ * @param locale BCP 47 locale tag (e.g. "en-US", "fr-FR"), 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 null
+ * @param options optional: minimalDays (integer 1–7, default 4)
  * @returns locale-relative week-numbering year, or null on invalid input
  *
  * @example getLocaleWeekYear("2024-06-15", "en-US") // 2024
- * @example getLocaleWeekYear("2022-01-01", "en-US") // 2022 (Jan 1 is always week 1 in en-US)
- * @example getLocaleWeekYear("2022-01-01", "de-DE") // 2021 (ISO-style: Jan 1, 2022 is a Saturday, in week 52 of 2021)
+ * @example getLocaleWeekYear("2022-01-01", "en-US", { minimalDays: 1 }) // 2022 — Jan 1 is always in week 1
+ * @example getLocaleWeekYear("2022-01-01", "en-US") // 2021 — ISO default: the week of Dec 26 holds 1 day of 2022
+ * @example getLocaleWeekYear("2022-01-01", "de-DE") // 2021 — Jan 1, 2022 is a Saturday, in week 52 of 2021
+ * @example getLocaleWeekYear("2022-01-01", "en-US", { minimalDays: 0 }) // null
+ * @example getLocaleWeekYear("+275760-09-13", "en-US") // 275760 (the last PlainDate; the next week 1 lies past the range)
  * @example getLocaleWeekYear("invalid", "en-US") // null
+ * @example getLocaleWeekYear("2024-12-29", ["en-US", "fr-FR"]) // 2025
  */
-export declare function getLocaleWeekYear(value: string, locale: string): number | null;
+export declare function getLocaleWeekYear(value: string, locale: string | string[], options?: {
+    minimalDays?: number;
+}): number | null;

package/dist/plain/calculate/getLocaleWeekYear.js

@@ -1,45 +1,65 @@
+// fallow-ignore-file code-duplication -- sibling variant keeps its own guard, parse and try/catch, by design
 import { Temporal } from "@js-temporal/polyfill";
-import { getLocaleFirstDayOfWeek, getLocaleMinimalDaysInFirstWeek, getLocaleWeekYearBounds, } from "../../internal/index.js";
+import { getLocaleFirstDayOfWeek, getLocaleWeekYearBounds, resolveMinimalDaysInFirstWeek, } from "../../internal/index.js";
 import { isValidDate } from "../validate/index.js";
+import { isOptionsArgument } from "../../internal/isObject.js";
 /**
- * Return the locale-relative week-numbering year `value` belongs to,
- * using `locale`'s first day of week and minimal-days-in-first-week
- * (e.g. en-US: week 1 always contains Jan 1; ISO/most European locales:
- * week 1 always contains Jan 4).
+ * Return the locale-relative week-numbering year `value` belongs to, from `locale`'s first day of
+ * week and a minimal-days-in-first-week rule.
  *
- * - Distinct from `value`'s calendar year, for the same reason
- *   `getWeekYear` is — late-December/early-January dates can belong to a
- *   different week-year than their calendar year, and the boundary
- *   depends on the locale's week-numbering rule.
- * - Distinct from `getWeekYear`: this uses the locale's first day of
- *   week and minimal-days rule (via `Intl.Locale.prototype.weekInfo`)
- *   instead of the fixed ISO rule (Monday-start, 4 minimal days) — the
- *   two can disagree on the same date near a year boundary.
- * - Resolves `locale`'s week-numbering rule via
- *   `Intl.Locale.prototype.weekInfo`.
- * - Returns null if `value` or `locale` is invalid.
+ * - Distinct from `value`'s calendar year, for the same reason `getWeekYear` is: late-December and
+ *   early-January dates can belong to a neighbouring week-year.
+ * - Week 1 is the week starting on `locale`'s first day of week that holds at least `minimalDays`
+ *   days of January (UTS #35 Part 4, Week Data). The first day of week comes from
+ *   `Intl.Locale.prototype.getWeekInfo`.
+ * - **`minimalDays` defaults to `4`, the ISO 8601 rule, on every runtime.** ECMA-402 does not expose
+ *   a locale's minimal days: Intl Locale Info returns only `firstDay` and `weekend`
+ *   (tc39/proposal-intl-locale-info#86), so older runtimes that still reported it disagreed with
+ *   newer ones about the same date. Pass CLDR's value when you need a locale's own rule: in CLDR 48
+ *   `weekData`, the world default (`001`) is `1` — week 1 always contains January 1, as in `US`,
+ *   `CA`, `MX`, `JP` and `CN` — and `4` is set for a list of mostly European regions such as `GB`,
+ *   `DE` and `FR`, where it matches this default.
+ * - Returns null if `value` or `locale` is invalid, or if `minimalDays` is not an integer from 1 to 7.
+ * - **Compatibility:** before 1.16.0 the default read the runtime's `minimalDays` where one was
+ *   exposed (Node 22), so a locale such as `en-US` got `1` there and `4` on Node 24 and later. Pass
+ *   `{ minimalDays: 1 }` to keep the Node 22 result for such a locale on every runtime.
  *
  * @param value ISO PlainDate string
- * @param locale BCP 47 locale tag (e.g. "en-US", "fr-FR")
+ * @param locale BCP 47 locale tag (e.g. "en-US", "fr-FR"), 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 null
+ * @param options optional: minimalDays (integer 1–7, default 4)
  * @returns locale-relative week-numbering year, or null on invalid input
  *
  * @example getLocaleWeekYear("2024-06-15", "en-US") // 2024
- * @example getLocaleWeekYear("2022-01-01", "en-US") // 2022 (Jan 1 is always week 1 in en-US)
- * @example getLocaleWeekYear("2022-01-01", "de-DE") // 2021 (ISO-style: Jan 1, 2022 is a Saturday, in week 52 of 2021)
+ * @example getLocaleWeekYear("2022-01-01", "en-US", { minimalDays: 1 }) // 2022 — Jan 1 is always in week 1
+ * @example getLocaleWeekYear("2022-01-01", "en-US") // 2021 — ISO default: the week of Dec 26 holds 1 day of 2022
+ * @example getLocaleWeekYear("2022-01-01", "de-DE") // 2021 — Jan 1, 2022 is a Saturday, in week 52 of 2021
+ * @example getLocaleWeekYear("2022-01-01", "en-US", { minimalDays: 0 }) // null
+ * @example getLocaleWeekYear("+275760-09-13", "en-US") // 275760 (the last PlainDate; the next week 1 lies past the range)
  * @example getLocaleWeekYear("invalid", "en-US") // null
+ * @example getLocaleWeekYear("2024-12-29", ["en-US", "fr-FR"]) // 2025
  */
-export function getLocaleWeekYear(value, locale) {
-    if (!isValidDate(value))
-        return null;
-    const firstDay = getLocaleFirstDayOfWeek(locale);
-    const minimalDays = getLocaleMinimalDaysInFirstWeek(locale);
-    if (firstDay === null || minimalDays === null)
-        return null;
+export function getLocaleWeekYear(value, locale, options) {
     try {
-        const date = Temporal.PlainDate.from(value);
-        return getLocaleWeekYearBounds(date, firstDay, minimalDays).weekYear;
+        if (!isOptionsArgument(options)) {
+            return null;
+        }
+        if (!isValidDate(value))
+            return null;
+        const firstDay = getLocaleFirstDayOfWeek(locale);
+        const minimalDays = resolveMinimalDaysInFirstWeek(options);
+        if (firstDay === null || minimalDays === null)
+            return null;
+        try {
+            const date = Temporal.PlainDate.from(value);
+            return getLocaleWeekYearBounds(date, firstDay, minimalDays).weekYear;
+        }
+        catch {
+            return null;
+        }
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return null;
     }
 }

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

@@ -1,8 +1,21 @@
 /**
  * Calculate the week number based on configurable week start day.
  *
- * - ISO (monday): Week 1 is the week containing the first Thursday (has at least 4 days in the year)
- * - US (sunday): Week 1 is the week containing Jan 1 (first week has at least 1 day)
+ * - `"monday"` (default) is the ISO 8601 week of the week-year: week 1 is the week containing the
+ *   first Thursday, so late-December days can be week 1 of the next year (`"2024-12-31"` → 1).
+ *   The result is 1–53.
+ * - `"sunday"` is the UTS #35 (Part 4, Week Data) week of the week-year with a Sunday first day
+ *   and minimal days 1: week 1 is the Sunday-first week containing 1 January, so the last days of
+ *   December before a mid-week 1 January are week 1 of the next year (`"2024-12-31"` → 1,
+ *   `"2000-12-31"` → 1). The result is 1–53.
+ * - `weekStartsOn` other than `"monday"` or `"sunday"` returns null; `undefined` is the default.
+ * - Returns null for invalid input, including every shape `isValidDate` rejects: a date-time,
+ *   zoned, basic-format or leap-second string, or a non-ISO calendar annotation. The annotations
+ *   Temporal ignores are accepted (`"2024-06-15[u-ca=iso8601]"` → 24).
+ * - Compatibility: earlier releases read those shapes loosely (`"2024-03-15T10:00"` → `11`).
+ *   Pass the date part alone, or use `Temporal.PlainDate.from(value).weekOfYear`.
+ * - **Compatibility:** before 1.16.0 `"sunday"` counted weeks within the calendar year with no
+ *   week-year rollover, so late-December days could be week 53 or 54.
  *
  * @param dateStr ISO PlainDate string (e.g. "2024-03-15")
  * @param weekStartsOn optional: "monday" (default) or "sunday"
@@ -12,6 +25,12 @@
  * @example getWeekNumber("2024-01-08") // 2
  * @example getWeekNumber("2024-12-31") // 1
  * @example getWeekNumber("2024-01-01", "sunday") // 1
+ * @example getWeekNumber("2024-12-28", "sunday") // 52
+ * @example getWeekNumber("2024-12-31", "sunday") // 1 (its Sunday-first week holds 1 January 2025)
+ * @example getWeekNumber("2000-12-30", "sunday") // 53
+ * @example getWeekNumber("2024-01-01", "tuesday" as never) // null (invalid weekStartsOn)
  * @example getWeekNumber("invalid") // null
+ * @example getWeekNumber("2024-03-15T10:00") // null (a date-time, not a PlainDate)
+ * @example getWeekNumber("2024-03-15T10:00".slice(0, 10)) // 11 (the date part)
  */
 export declare function getWeekNumber(dateStr: string, weekStartsOn?: "monday" | "sunday"): number | null;

package/dist/plain/calculate/getWeekNumber.js

@@ -1,9 +1,23 @@
 import { Temporal } from "@js-temporal/polyfill";
+import { isValidDate } from "../validate/index.js";
 /**
  * Calculate the week number based on configurable week start day.
  *
- * - ISO (monday): Week 1 is the week containing the first Thursday (has at least 4 days in the year)
- * - US (sunday): Week 1 is the week containing Jan 1 (first week has at least 1 day)
+ * - `"monday"` (default) is the ISO 8601 week of the week-year: week 1 is the week containing the
+ *   first Thursday, so late-December days can be week 1 of the next year (`"2024-12-31"` → 1).
+ *   The result is 1–53.
+ * - `"sunday"` is the UTS #35 (Part 4, Week Data) week of the week-year with a Sunday first day
+ *   and minimal days 1: week 1 is the Sunday-first week containing 1 January, so the last days of
+ *   December before a mid-week 1 January are week 1 of the next year (`"2024-12-31"` → 1,
+ *   `"2000-12-31"` → 1). The result is 1–53.
+ * - `weekStartsOn` other than `"monday"` or `"sunday"` returns null; `undefined` is the default.
+ * - Returns null for invalid input, including every shape `isValidDate` rejects: a date-time,
+ *   zoned, basic-format or leap-second string, or a non-ISO calendar annotation. The annotations
+ *   Temporal ignores are accepted (`"2024-06-15[u-ca=iso8601]"` → 24).
+ * - Compatibility: earlier releases read those shapes loosely (`"2024-03-15T10:00"` → `11`).
+ *   Pass the date part alone, or use `Temporal.PlainDate.from(value).weekOfYear`.
+ * - **Compatibility:** before 1.16.0 `"sunday"` counted weeks within the calendar year with no
+ *   week-year rollover, so late-December days could be week 53 or 54.
  *
  * @param dateStr ISO PlainDate string (e.g. "2024-03-15")
  * @param weekStartsOn optional: "monday" (default) or "sunday"
@@ -13,25 +27,32 @@ import { Temporal } from "@js-temporal/polyfill";
  * @example getWeekNumber("2024-01-08") // 2
  * @example getWeekNumber("2024-12-31") // 1
  * @example getWeekNumber("2024-01-01", "sunday") // 1
+ * @example getWeekNumber("2024-12-28", "sunday") // 52
+ * @example getWeekNumber("2024-12-31", "sunday") // 1 (its Sunday-first week holds 1 January 2025)
+ * @example getWeekNumber("2000-12-30", "sunday") // 53
+ * @example getWeekNumber("2024-01-01", "tuesday" as never) // null (invalid weekStartsOn)
  * @example getWeekNumber("invalid") // null
+ * @example getWeekNumber("2024-03-15T10:00") // null (a date-time, not a PlainDate)
+ * @example getWeekNumber("2024-03-15T10:00".slice(0, 10)) // 11 (the date part)
  */
 export function getWeekNumber(dateStr, weekStartsOn = "monday") {
+    if (!isValidDate(dateStr) ||
+        (weekStartsOn !== "monday" && weekStartsOn !== "sunday"))
+        return null;
     try {
         const date = Temporal.PlainDate.from(dateStr);
         if (weekStartsOn === "monday") {
             const isoWeek = date.weekOfYear;
             return isoWeek ?? null;
         }
-        const yearStart = Temporal.PlainDate.from({
-            year: date.year,
-            month: 1,
-            day: 1,
-        });
-        const firstDayOfWeek = yearStart.dayOfWeek;
-        const daysSinceSunday = firstDayOfWeek === 7 ? 0 : firstDayOfWeek;
-        const daysSinceJan1 = date.dayOfYear - 1;
-        const result = Math.floor((daysSinceJan1 + daysSinceSunday) / 7) + 1;
-        return result;
+        // UTS #35 week of year, first day Sunday, minimal days 1: a week belongs to the week-year of
+        // its Saturday, and week 1 is the one whose Saturday falls in 1–7 January. Counted on day of
+        // year so a week ending past +275760-09-13 still resolves.
+        const daysToSaturday = 6 - (date.dayOfWeek % 7);
+        const saturdayDayOfYear = date.dayOfYear + daysToSaturday;
+        if (saturdayDayOfYear > date.daysInYear)
+            return 1;
+        return Math.floor((saturdayDayOfYear - 1) / 7) + 1;
     }
     catch {
         return null;

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

@@ -14,13 +14,15 @@
  * - Returns null if `value` or `locale` is invalid.
  *
  * @param value ISO PlainDate string
- * @param locale BCP 47 locale tag (e.g. "en-US", "fr-FR")
+ * @param locale BCP 47 locale tag (e.g. "en-US", "fr-FR"), 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 null
  * @returns 1-based week-of-month row, or null on invalid input
  *
  * @example getWeekOfMonth("2024-02-01", "en-US") // 1
  * @example getWeekOfMonth("2024-02-29", "en-US") // 5
  * @example getWeekOfMonth("2026-02-01", "en-US") // 1
  * @example getWeekOfMonth("2026-02-01", "en-GB") // 1
+ * @example getWeekOfMonth("-271821-04-30", "en-US") // 5 (the first representable month; its 1st lies before the range)
  * @example getWeekOfMonth("invalid", "en-US") // null
+ * @example getWeekOfMonth("2024-05-12", ["fr-FR", "en-US"]) // 2
  */
-export declare function getWeekOfMonth(value: string, locale: string): number | null;
+export declare function getWeekOfMonth(value: string, locale: string | string[]): number | null;

package/dist/plain/calculate/getWeekOfMonth.js

@@ -1,3 +1,4 @@
+// fallow-ignore-file code-duplication -- sibling variant keeps its own guard, parse and try/catch, by design
 import { Temporal } from "@js-temporal/polyfill";
 import { getLocaleFirstDayOfWeek, monthGridWeekRow } from "../../internal/index.js";
 import { isValidDate } from "../validate/index.js";
@@ -17,14 +18,16 @@ import { isValidDate } from "../validate/index.js";
  * - Returns null if `value` or `locale` is invalid.
  *
  * @param value ISO PlainDate string
- * @param locale BCP 47 locale tag (e.g. "en-US", "fr-FR")
+ * @param locale BCP 47 locale tag (e.g. "en-US", "fr-FR"), 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 null
  * @returns 1-based week-of-month row, or null on invalid input
  *
  * @example getWeekOfMonth("2024-02-01", "en-US") // 1
  * @example getWeekOfMonth("2024-02-29", "en-US") // 5
  * @example getWeekOfMonth("2026-02-01", "en-US") // 1
  * @example getWeekOfMonth("2026-02-01", "en-GB") // 1
+ * @example getWeekOfMonth("-271821-04-30", "en-US") // 5 (the first representable month; its 1st lies before the range)
  * @example getWeekOfMonth("invalid", "en-US") // null
+ * @example getWeekOfMonth("2024-05-12", ["fr-FR", "en-US"]) // 2
  */
 export function getWeekOfMonth(value, locale) {
     if (!isValidDate(value))
@@ -34,8 +37,10 @@ export function getWeekOfMonth(value, locale) {
         return null;
     try {
         const date = Temporal.PlainDate.from(value);
-        const firstOfMonth = date.with({ day: 1 });
-        return monthGridWeekRow(firstOfMonth, firstDay, date.day);
+        // The 1st's weekday, counted back from the date rather than built with `with({ day: 1 })`:
+        // the 1st of the first representable month (April -271821) lies before the range.
+        const dayOfWeek = ((((date.dayOfWeek - date.day) % 7) + 7) % 7) + 1;
+        return monthGridWeekRow({ dayOfWeek }, firstDay, date.day);
     }
     catch {
         return null;