@northguild/gmt 1.15.0 → 1.17.0

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

@@ -1,24 +1,35 @@
 /**
- * Return the number of weeks (52 or 53) in the locale week-numbering year
- * containing `value`, using `locale`'s first day of week and
- * minimal-days-in-first-week.
+ * Return the number of weeks (52 or 53) in the locale week-numbering year containing `value`, from
+ * `locale`'s first day of week and a minimal-days-in-first-week rule.
  *
- * - `getWeeksInYear`'s locale-relative counterpart — that function uses
- *   the fixed ISO rule, this one uses `locale`'s week-numbering rule
- *   (via `Intl.Locale.prototype.weekInfo`), and the two can disagree on
- *   the same date.
- * - Computed as the number of calendar days between the locale
- *   week-year's start and the next week-year's start, divided by 7 —
- *   always a whole number, since both bounds fall on the locale's first
- *   day of week.
- * - Returns null if `value` or `locale` is invalid.
+ * - `getWeeksInYear`'s locale-relative counterpart: that function uses the fixed ISO rule, this one
+ *   uses `locale`'s first day of week, and the two can disagree on the same date.
+ * - Computed as the calendar days between this week-year's start and the next one's, divided by 7 —
+ *   always whole, since both starts fall on the locale's first day of week. Counted by day
+ *   arithmetic, so a start outside the representable range still counts.
+ * - **`minimalDays` defaults to `4`, the ISO 8601 rule, on every runtime.** ECMA-402 does not expose
+ *   a locale's minimal days (tc39/proposal-intl-locale-info#86). CLDR 48's world default is `1`
+ *   (`US` included) and `4` is set for mostly European regions; pass the locale's value when it
+ *   differs. See `getLocaleWeekYear`.
+ * - 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 52 or 53, or null on invalid input
  *
  * @example getWeeksInLocaleWeekYear("2024-06-15", "en-US") // 52
+ * @example getWeeksInLocaleWeekYear("2022-06-15", "en-US", { minimalDays: 1 }) // 53 — Dec 26, 2021 to Jan 1, 2023
+ * @example getWeeksInLocaleWeekYear("2022-06-15", "en-US") // 52 — ISO default: Jan 2, 2022 to Jan 1, 2023
  * @example getWeeksInLocaleWeekYear("2020-06-15", "de-DE") // 53
+ * @example getWeeksInLocaleWeekYear("2024-06-15", "en-US", { minimalDays: 8 }) // null
+ * @example getWeeksInLocaleWeekYear("+275760-09-13", "en-US") // 53 (its end, the week 1 of +275761, lies past the range)
  * @example getWeeksInLocaleWeekYear("invalid", "en-US") // null
+ * @example getWeeksInLocaleWeekYear("2024-12-29", ["fr-FR", "en-US"]) // 52
  */
-export declare function getWeeksInLocaleWeekYear(value: string, locale: string): number | null;
+export declare function getWeeksInLocaleWeekYear(value: string, locale: string | string[], options?: {
+    minimalDays?: number;
+}): number | null;

package/dist/plain/calculate/getWeeksInLocaleWeekYear.js

@@ -1,43 +1,63 @@
+// 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 number of weeks (52 or 53) in the locale week-numbering year
- * containing `value`, using `locale`'s first day of week and
- * minimal-days-in-first-week.
+ * Return the number of weeks (52 or 53) in the locale week-numbering year containing `value`, from
+ * `locale`'s first day of week and a minimal-days-in-first-week rule.
  *
- * - `getWeeksInYear`'s locale-relative counterpart — that function uses
- *   the fixed ISO rule, this one uses `locale`'s week-numbering rule
- *   (via `Intl.Locale.prototype.weekInfo`), and the two can disagree on
- *   the same date.
- * - Computed as the number of calendar days between the locale
- *   week-year's start and the next week-year's start, divided by 7 —
- *   always a whole number, since both bounds fall on the locale's first
- *   day of week.
- * - Returns null if `value` or `locale` is invalid.
+ * - `getWeeksInYear`'s locale-relative counterpart: that function uses the fixed ISO rule, this one
+ *   uses `locale`'s first day of week, and the two can disagree on the same date.
+ * - Computed as the calendar days between this week-year's start and the next one's, divided by 7 —
+ *   always whole, since both starts fall on the locale's first day of week. Counted by day
+ *   arithmetic, so a start outside the representable range still counts.
+ * - **`minimalDays` defaults to `4`, the ISO 8601 rule, on every runtime.** ECMA-402 does not expose
+ *   a locale's minimal days (tc39/proposal-intl-locale-info#86). CLDR 48's world default is `1`
+ *   (`US` included) and `4` is set for mostly European regions; pass the locale's value when it
+ *   differs. See `getLocaleWeekYear`.
+ * - 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 52 or 53, or null on invalid input
  *
  * @example getWeeksInLocaleWeekYear("2024-06-15", "en-US") // 52
+ * @example getWeeksInLocaleWeekYear("2022-06-15", "en-US", { minimalDays: 1 }) // 53 — Dec 26, 2021 to Jan 1, 2023
+ * @example getWeeksInLocaleWeekYear("2022-06-15", "en-US") // 52 — ISO default: Jan 2, 2022 to Jan 1, 2023
  * @example getWeeksInLocaleWeekYear("2020-06-15", "de-DE") // 53
+ * @example getWeeksInLocaleWeekYear("2024-06-15", "en-US", { minimalDays: 8 }) // null
+ * @example getWeeksInLocaleWeekYear("+275760-09-13", "en-US") // 53 (its end, the week 1 of +275761, lies past the range)
  * @example getWeeksInLocaleWeekYear("invalid", "en-US") // null
+ * @example getWeeksInLocaleWeekYear("2024-12-29", ["fr-FR", "en-US"]) // 52
  */
-export function getWeeksInLocaleWeekYear(value, locale) {
-    if (!isValidDate(value))
-        return null;
-    const firstDay = getLocaleFirstDayOfWeek(locale);
-    const minimalDays = getLocaleMinimalDaysInFirstWeek(locale);
-    if (firstDay === null || minimalDays === null)
-        return null;
+export function getWeeksInLocaleWeekYear(value, locale, options) {
     try {
-        const date = Temporal.PlainDate.from(value);
-        const { start, end } = getLocaleWeekYearBounds(date, firstDay, minimalDays);
-        const days = start.until(end, { largestUnit: "days" }).days;
-        return days / 7;
+        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);
+            const { startOffsetDays, endOffsetDays } = getLocaleWeekYearBounds(date, firstDay, minimalDays);
+            return (endOffsetDays - startOffsetDays) / 7;
+        }
+        catch {
+            return null;
+        }
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return null;
     }
 }

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

@@ -12,12 +12,14 @@
  * - 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 number of week-rows the month spans (4-6), or null on invalid input
  *
  * @example getWeeksInMonth("2024-02-15", "en-US") // 5
  * @example getWeeksInMonth("2026-02-15", "en-US") // 4
  * @example getWeeksInMonth("2026-02-15", "en-GB") // 5
+ * @example getWeeksInMonth("-271821-04-19", "en-US") // 5 (the first representable month; its 1st lies before the range)
  * @example getWeeksInMonth("invalid", "en-US") // null
+ * @example getWeeksInMonth("2024-06-15", ["en-US", "fr-FR"]) // 6
  */
-export declare function getWeeksInMonth(value: string, locale: string): number | null;
+export declare function getWeeksInMonth(value: string, locale: string | string[]): number | null;

package/dist/plain/calculate/getWeeksInMonth.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";
@@ -15,13 +16,15 @@ 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 number of week-rows the month spans (4-6), or null on invalid input
  *
  * @example getWeeksInMonth("2024-02-15", "en-US") // 5
  * @example getWeeksInMonth("2026-02-15", "en-US") // 4
  * @example getWeeksInMonth("2026-02-15", "en-GB") // 5
+ * @example getWeeksInMonth("-271821-04-19", "en-US") // 5 (the first representable month; its 1st lies before the range)
  * @example getWeeksInMonth("invalid", "en-US") // null
+ * @example getWeeksInMonth("2024-06-15", ["en-US", "fr-FR"]) // 6
  */
 export function getWeeksInMonth(value, locale) {
     if (!isValidDate(value))
@@ -31,8 +34,10 @@ export function getWeeksInMonth(value, locale) {
         return null;
     try {
         const date = Temporal.PlainDate.from(value);
-        const firstOfMonth = date.with({ day: 1 });
-        return monthGridWeekRow(firstOfMonth, firstDay, date.daysInMonth);
+        // 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.daysInMonth);
     }
     catch {
         return null;

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

@@ -6,10 +6,10 @@
  *   not its calendar year — late-December/early-January dates can belong to
  *   a different ISO week-year than their calendar year (e.g. 2021-01-01 is
  *   ISO week-year 2020's week 53).
- * - December 28 always falls in the ISO week-numbering year's final week
- *   (ISO week 1 always contains Jan 4, so Dec 28 — exactly 52 weeks after —
- *   is always in the last week), so its `weekOfYear` reports the year's
- *   total week count.
+ * - Counted as the days from the week-year's week 1 (the Monday-started week
+ *   holding January 4) to the next week-year's week 1, divided by 7. Computed
+ *   by day arithmetic, so the dates at the range edges count too, although
+ *   the neighbouring week 1 lies outside the representable range.
  * - Returns null on invalid input.
  *
  * @param value ISO PlainDate string
@@ -18,6 +18,7 @@
  * @example getWeeksInYear("2024-06-15") // 52
  * @example getWeeksInYear("2020-06-15") // 53
  * @example getWeeksInYear("2021-01-01") // 53 (belongs to ISO week-year 2020)
+ * @example getWeeksInYear("+275760-09-13") // 52 (the last PlainDate)
  * @example getWeeksInYear("invalid") // null
  */
 export declare function getWeeksInYear(value: string): number | null;

package/dist/plain/calculate/getWeeksInYear.js

@@ -1,4 +1,5 @@
 import { Temporal } from "@js-temporal/polyfill";
+import { getLocaleWeekYearBounds } from "../../internal/index.js";
 import { isValidDate } from "../validate/index.js";
 /**
  * Return the number of ISO weeks (52 or 53) in the ISO week-numbering year
@@ -8,10 +9,10 @@ import { isValidDate } from "../validate/index.js";
  *   not its calendar year — late-December/early-January dates can belong to
  *   a different ISO week-year than their calendar year (e.g. 2021-01-01 is
  *   ISO week-year 2020's week 53).
- * - December 28 always falls in the ISO week-numbering year's final week
- *   (ISO week 1 always contains Jan 4, so Dec 28 — exactly 52 weeks after —
- *   is always in the last week), so its `weekOfYear` reports the year's
- *   total week count.
+ * - Counted as the days from the week-year's week 1 (the Monday-started week
+ *   holding January 4) to the next week-year's week 1, divided by 7. Computed
+ *   by day arithmetic, so the dates at the range edges count too, although
+ *   the neighbouring week 1 lies outside the representable range.
  * - Returns null on invalid input.
  *
  * @param value ISO PlainDate string
@@ -20,22 +21,16 @@ import { isValidDate } from "../validate/index.js";
  * @example getWeeksInYear("2024-06-15") // 52
  * @example getWeeksInYear("2020-06-15") // 53
  * @example getWeeksInYear("2021-01-01") // 53 (belongs to ISO week-year 2020)
+ * @example getWeeksInYear("+275760-09-13") // 52 (the last PlainDate)
  * @example getWeeksInYear("invalid") // null
  */
 export function getWeeksInYear(value) {
     if (!isValidDate(value))
         return null;
     try {
-        const date = Temporal.PlainDate.from(value);
-        const yearOfWeek = date.yearOfWeek;
-        if (yearOfWeek === undefined)
-            return null;
-        const lastWeekAnchor = Temporal.PlainDate.from({
-            year: yearOfWeek,
-            month: 12,
-            day: 28,
-        });
-        return lastWeekAnchor.weekOfYear ?? null;
+        // ISO 8601 week-numbering: weeks start on Monday and week 1 holds January 4 (4 of its days).
+        const { startOffsetDays, endOffsetDays } = getLocaleWeekYearBounds(Temporal.PlainDate.from(value), 1, 4);
+        return (endOffsetDays - startOffsetDays) / 7;
     }
     catch {
         return null;

package/dist/plain/calculate/maxDate.js

@@ -13,21 +13,28 @@ import { isValidDate } from "../validate/index.js";
  * @example maxDate([]) // null
  */
 export function maxDate(dates) {
-    if (!dates.length)
-        return null;
-    const valid = dates.filter(isValidDate);
-    if (!valid.length)
-        return null;
     try {
-        const max = valid.reduce((currentMax, candidateStr) => {
-            const candidate = Temporal.PlainDate.from(candidateStr);
-            return Temporal.PlainDate.compare(candidate, currentMax) > 0
-                ? candidate
-                : currentMax;
-        }, Temporal.PlainDate.from(valid[0]));
-        return max.toString();
+        if (!Array.isArray(dates) || !dates.length)
+            return null;
+        const valid = dates.filter(isValidDate);
+        if (!valid.length)
+            return null;
+        try {
+            const max = valid.reduce((currentMax, candidateStr) => {
+                const candidate = Temporal.PlainDate.from(candidateStr);
+                return Temporal.PlainDate.compare(candidate, currentMax) > 0
+                    ? candidate
+                    : currentMax;
+            }, Temporal.PlainDate.from(valid[0]));
+            return max.toString();
+        }
+        catch {
+            return null;
+        }
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return null;
     }
 }

package/dist/plain/calculate/maxDateTime.js

@@ -13,21 +13,28 @@ import { isValidDateTime } from "../validate/index.js";
  * @example maxDateTime([]) // null
  */
 export function maxDateTime(dateTimes) {
-    if (!dateTimes.length)
-        return null;
-    const valid = dateTimes.filter(isValidDateTime);
-    if (!valid.length)
-        return null;
     try {
-        const max = valid.reduce((currentMax, candidateStr) => {
-            const candidate = Temporal.PlainDateTime.from(candidateStr);
-            return Temporal.PlainDateTime.compare(candidate, currentMax) > 0
-                ? candidate
-                : currentMax;
-        }, Temporal.PlainDateTime.from(valid[0]));
-        return max.toString();
+        if (!Array.isArray(dateTimes) || !dateTimes.length)
+            return null;
+        const valid = dateTimes.filter(isValidDateTime);
+        if (!valid.length)
+            return null;
+        try {
+            const max = valid.reduce((currentMax, candidateStr) => {
+                const candidate = Temporal.PlainDateTime.from(candidateStr);
+                return Temporal.PlainDateTime.compare(candidate, currentMax) > 0
+                    ? candidate
+                    : currentMax;
+            }, Temporal.PlainDateTime.from(valid[0]));
+            return max.toString();
+        }
+        catch {
+            return null;
+        }
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return null;
     }
 }

package/dist/plain/calculate/maxTime.js

@@ -13,21 +13,28 @@ import { isValidTime } from "../validate/index.js";
  * @example maxTime([]) // null
  */
 export function maxTime(times) {
-    if (!times.length)
-        return null;
-    const valid = times.filter(isValidTime);
-    if (!valid.length)
-        return null;
     try {
-        const max = valid.reduce((currentMax, candidateStr) => {
-            const candidate = Temporal.PlainTime.from(candidateStr);
-            return Temporal.PlainTime.compare(candidate, currentMax) > 0
-                ? candidate
-                : currentMax;
-        }, Temporal.PlainTime.from(valid[0]));
-        return max.toString();
+        if (!Array.isArray(times) || !times.length)
+            return null;
+        const valid = times.filter(isValidTime);
+        if (!valid.length)
+            return null;
+        try {
+            const max = valid.reduce((currentMax, candidateStr) => {
+                const candidate = Temporal.PlainTime.from(candidateStr);
+                return Temporal.PlainTime.compare(candidate, currentMax) > 0
+                    ? candidate
+                    : currentMax;
+            }, Temporal.PlainTime.from(valid[0]));
+            return max.toString();
+        }
+        catch {
+            return null;
+        }
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return null;
     }
 }

package/dist/plain/calculate/minDate.js

@@ -13,21 +13,28 @@ import { isValidDate } from "../validate/index.js";
  * @example minDate([]) // null
  */
 export function minDate(dates) {
-    if (!dates.length)
-        return null;
-    const valid = dates.filter(isValidDate);
-    if (!valid.length)
-        return null;
     try {
-        const min = valid.reduce((currentMin, candidateStr) => {
-            const candidate = Temporal.PlainDate.from(candidateStr);
-            return Temporal.PlainDate.compare(candidate, currentMin) < 0
-                ? candidate
-                : currentMin;
-        }, Temporal.PlainDate.from(valid[0]));
-        return min.toString();
+        if (!Array.isArray(dates) || !dates.length)
+            return null;
+        const valid = dates.filter(isValidDate);
+        if (!valid.length)
+            return null;
+        try {
+            const min = valid.reduce((currentMin, candidateStr) => {
+                const candidate = Temporal.PlainDate.from(candidateStr);
+                return Temporal.PlainDate.compare(candidate, currentMin) < 0
+                    ? candidate
+                    : currentMin;
+            }, Temporal.PlainDate.from(valid[0]));
+            return min.toString();
+        }
+        catch {
+            return null;
+        }
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return null;
     }
 }

package/dist/plain/calculate/minDateTime.js

@@ -13,21 +13,28 @@ import { isValidDateTime } from "../validate/index.js";
  * @example minDateTime([]) // null
  */
 export function minDateTime(dateTimes) {
-    if (!dateTimes.length)
-        return null;
-    const valid = dateTimes.filter(isValidDateTime);
-    if (!valid.length)
-        return null;
     try {
-        const min = valid.reduce((currentMin, candidateStr) => {
-            const candidate = Temporal.PlainDateTime.from(candidateStr);
-            return Temporal.PlainDateTime.compare(candidate, currentMin) < 0
-                ? candidate
-                : currentMin;
-        }, Temporal.PlainDateTime.from(valid[0]));
-        return min.toString();
+        if (!Array.isArray(dateTimes) || !dateTimes.length)
+            return null;
+        const valid = dateTimes.filter(isValidDateTime);
+        if (!valid.length)
+            return null;
+        try {
+            const min = valid.reduce((currentMin, candidateStr) => {
+                const candidate = Temporal.PlainDateTime.from(candidateStr);
+                return Temporal.PlainDateTime.compare(candidate, currentMin) < 0
+                    ? candidate
+                    : currentMin;
+            }, Temporal.PlainDateTime.from(valid[0]));
+            return min.toString();
+        }
+        catch {
+            return null;
+        }
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return null;
     }
 }

package/dist/plain/calculate/minTime.js

@@ -13,21 +13,28 @@ import { isValidTime } from "../validate/index.js";
  * @example minTime([]) // null
  */
 export function minTime(times) {
-    if (!times.length)
-        return null;
-    const valid = times.filter(isValidTime);
-    if (!valid.length)
-        return null;
     try {
-        const min = valid.reduce((currentMin, candidateStr) => {
-            const candidate = Temporal.PlainTime.from(candidateStr);
-            return Temporal.PlainTime.compare(candidate, currentMin) < 0
-                ? candidate
-                : currentMin;
-        }, Temporal.PlainTime.from(valid[0]));
-        return min.toString();
+        if (!Array.isArray(times) || !times.length)
+            return null;
+        const valid = times.filter(isValidTime);
+        if (!valid.length)
+            return null;
+        try {
+            const min = valid.reduce((currentMin, candidateStr) => {
+                const candidate = Temporal.PlainTime.from(candidateStr);
+                return Temporal.PlainTime.compare(candidate, currentMin) < 0
+                    ? candidate
+                    : currentMin;
+            }, Temporal.PlainTime.from(valid[0]));
+            return min.toString();
+        }
+        catch {
+            return null;
+        }
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return null;
     }
 }

package/dist/plain/calculate/nextWeekday.js

@@ -1,6 +1,8 @@
+// fallow-ignore-file code-duplication -- sibling variant keeps its own guard, parse and try/catch, by design
 import { Temporal } from "@js-temporal/polyfill";
 import { advanceToWeekday, isValidDayOfWeek } from "../../internal/index.js";
 import { isValidDate } from "../validate/index.js";
+import { isOptionsArgument } from "../../internal/isObject.js";
 /**
  * Return a PlainDate ISO string for the next occurrence of `dayOfWeek` on or after `value`.
  *
@@ -35,6 +37,9 @@ import { isValidDate } from "../validate/index.js";
  * @example nextWeekday("2024-03-15", 8) // "" (dayOfWeek out of range)
  */
 export function nextWeekday(value, dayOfWeek, options) {
+    if (!isOptionsArgument(options)) {
+        return "";
+    }
     if (!isValidDate(value) || !isValidDayOfWeek(dayOfWeek))
         return "";
     try {

package/dist/plain/calculate/previousWeekday.js

@@ -1,6 +1,8 @@
+// fallow-ignore-file code-duplication -- sibling variant keeps its own guard, parse and try/catch, by design
 import { Temporal } from "@js-temporal/polyfill";
 import { advanceToWeekday, isValidDayOfWeek } from "../../internal/index.js";
 import { isValidDate } from "../validate/index.js";
+import { isOptionsArgument } from "../../internal/isObject.js";
 /**
  * Return a PlainDate ISO string for the previous occurrence of `dayOfWeek` on or before `value`.
  *
@@ -35,6 +37,9 @@ import { isValidDate } from "../validate/index.js";
  * @example previousWeekday("2024-03-15", 0) // "" (dayOfWeek out of range)
  */
 export function previousWeekday(value, dayOfWeek, options) {
+    if (!isOptionsArgument(options)) {
+        return "";
+    }
     if (!isValidDate(value) || !isValidDayOfWeek(dayOfWeek))
         return "";
     try {

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

@@ -4,9 +4,20 @@ import type { DateUnit } from "../../types/index.js";
  * Round an ISO 8601 date string to the specified date unit.
  *
  * - Returns "" for invalid inputs.
- * - Accepts date units: "year", "month", "week", "day".
+ * - Accepts date units: "year", "month", "week", "day", each in its singular or plural form
+ *   ("month" or "months"), as Temporal's GetTemporalUnitValuedOption accepts both (§13.17).
  * - Time units ("hour", "minute", etc.) are rejected and return "".
- * - All date units use manual start-of-unit rounding.
+ * - All date units use manual start-of-unit rounding. Weeks start on Monday.
+ * - The rounding grid is anchored at the unit containing `value`, so `"halfEven"` breaks an exact
+ *   tie towards that unit's start (multiple 0, the even one).
+ * - The position within the unit is measured towards the next start, so a date in a unit that
+ *   began before the first representable date (`-271821-04-19`) still rounds up to the next start.
+ *   When it rounds down to that unrepresentable start, the result is "".
+ * - In the last representable year (`+275760`) a date that rounds down still returns its unit's
+ *   start; only rounding up past `+275760-09-13` returns "".
+ * - `roundingIncrement` and `roundingMode` are read as Temporal reads them: a non-integer increment
+ *   is truncated (`1.5` rounds by 1), an increment below 1 or not finite returns "", and a
+ *   `roundingMode` outside Temporal's nine returns "" (previously it floored silently).
  * - Wraps all Temporal calls in try-catch; returns "" on any error.
  *
  * @param value ISO 8601 date string
@@ -14,13 +25,20 @@ import type { DateUnit } from "../../types/index.js";
  * @returns Rounded ISO 8601 date string, or "" on invalid input
  *
  * @example roundDate("2024-06-15", { smallestUnit: "year" }) // "2024-01-01"
- * @example roundDate("2024-06-15", { smallestUnit: "month" }) // "2024-07-01"
- * @example roundDate("2024-06-15", { smallestUnit: "week" }) // "2024-06-16"
+ * @example roundDate("2024-06-15", { smallestUnit: "month" }) // "2024-06-01" (14 of 30 days in: rounds down)
+ * @example roundDate("2024-06-16", { smallestUnit: "month" }) // "2024-07-01" (half way: rounds up)
+ * @example roundDate("2024-06-15", { smallestUnit: "week" }) // "2024-06-17" (a Saturday: the next Monday is closer)
  * @example roundDate("2024-06-15", { smallestUnit: "day" }) // "2024-06-15"
+ * @example roundDate("2024-06-15", { smallestUnit: "months" }) // "2024-06-01" (plural unit name)
+ * @example roundDate("-271821-04-19", { smallestUnit: "month" }) // "-271821-05-01" (the month began before the range)
+ * @example roundDate("+275760-06-15", { smallestUnit: "year", roundingMode: "floor" }) // "+275760-01-01" (the next year is past the range)
+ * @example roundDate("+275760-06-15", { smallestUnit: "year", roundingMode: "ceil" }) // "" (+275761-01-01 is past the range)
+ * @example roundDate("2024-05-20", { smallestUnit: "month", roundingIncrement: 1.5 }) // "2024-06-01" (the increment truncates to 1)
+ * @example roundDate("2024-05-20", { smallestUnit: "month", roundingMode: "bogus" as never }) // ""
  * @example roundDate("invalid", { smallestUnit: "year" }) // ""
  */
 export declare function roundDate(value: string, options: {
-    smallestUnit: DateUnit;
+    smallestUnit: Temporal.SmallestUnit<DateUnit>;
     roundingIncrement?: number;
     roundingMode?: Temporal.RoundingMode;
 }): string;