@northguild/gmt 1.19.0 → 1.20.0

package/dist/calendar/calculate/getFiscalPeriod.d.ts

@@ -7,31 +7,37 @@ import type { FiscalCalendar } from "../../types/index.js";
  * insertion fall out of `calendar` — nothing here is bundled, because there is no single
  * correct retail calendar.
  *
- * - `calendar.pattern` is the weeks-per-period shape of a quarter: `"4-5-4"` (the NRF retail
- *   standard), `"4-4-5"` or `"5-4-4"`. Four quarters of 13 weeks make the 52-week year.
+ * - `calendar.pattern` is the weeks-per-period shape of a quarter: `"4-5-4"`, `"4-4-5"` or
+ *   `"5-4-4"`. Four quarters of 13 weeks make the 52-week year.
  * - **`calendar.yearEndsOn` states the year-end *rule*, by example, not one year's end.**
  *   Fiscal years end on that date's weekday, on the occurrence nearest that date's month and
- *   day. The NRF's published rule — "the Saturday nearest to January 31"
- *   ([NRF 4-5-4 calendar](https://nrf.com/resources/4-5-4-calendar)) — is `"2026-01-31"`, a
- *   Saturday falling exactly on January 31. Passing a published year end from a 53-week year
- *   instead (`"2024-02-03"`) states a different rule, because that date sits three days off
- *   the target the rule is centred on, and yields a different, self-consistent calendar.
- * - Weeks are numbered through the fiscal year as the NRF publishes them. A 53rd week is
- *   appended to period 12 — the NRF adds it "to the end of the calendar" — which makes a 4-5-4
- *   year's final quarter 4-5-5.
- * - The `year` label follows the NRF: fiscal 2023 runs 2023-01-29 to 2024-02-03. Organisations
- *   labelling by the end year should add one.
- * - **`year` is not a unique key for a rule anchored near 1 January.** A 52/53-week year is
- *   364 or 371 days, so it drifts against the calendar, and no label taken from a calendar
- *   year survives that for every anchor. Under `yearEndsOn: "2022-12-31"` — the Saturday
- *   nearest to 31 December — two consecutive fiscal years both start in 2023 and share the
- *   label, and 2020, 2025 and 2031 label no fiscal year at all. Grouping by `year` there
- *   merges 104 weeks and drops a year. `"2027-01-02"` states a different rule, the Saturday
- *   nearest to 2 January: it too gives 2023 twice, merging 105 weeks, and skips 2018, 2024
- *   and 2029. January/February anchors like the NRF's
- *   are unaffected. If your rule sits near a year boundary, key on the fiscal year's own start
- *   date — which `yearEndsOn` determines, and which is yours to enumerate — not on `year`.
- *   GMT does not invent a label the inputs do not fix.
+ *   day. One published 4-5-4 example (NRF, US) adds a 53rd week when "there are four or more
+ *   days left in January" ([NRF 4-5-4 calendar](https://nrf.com/resources/4-5-4-calendar)),
+ *   which puts its year end on the Saturday nearest January 31. As `yearEndsOn` that is
+ *   `"2026-01-31"`, a Saturday falling exactly on January 31. Passing a published year end
+ *   from a 53-week year instead (`"2024-02-03"`) states a different rule, because that date
+ *   sits three days off the target the rule is centred on, and yields a different,
+ *   self-consistent calendar.
+ * - IFRS 18 ¶29 (formerly IAS 1 ¶37; IFRS 18 applies to reporting periods beginning on or
+ *   after 2027-01-01) does not preclude reporting for a 52-week period, and a 53-week year
+ *   follows from it. No international standard says where the 53rd week goes or which
+ *   calendar year names the fiscal year, and published calendars disagree on both. So
+ *   `calendar.extraWeek` and `calendar.yearLabel` are required, and there is no default.
+ * - `calendar.extraWeek` is the period a 53rd week is added to: `"firstPeriod"` (ONS, UK: "a
+ *   five week January") or `"lastPeriod"` (NRF, US: "to the end of the calendar").
+ * - `calendar.yearLabel` names the fiscal year: `"startYear"` (NRF, US), `"endYear"`, the
+ *   year its last day falls in, or `"majorityYear"`, the calendar year holding the most days
+ *   (ONS, UK). IFRS 18 ¶27(c) (formerly IAS 1 ¶51(c)) lets a reporting period be identified
+ *   by the date it ends, which supports `"endYear"`. GMT rule: a 182/182 split goes to the
+ *   end year, for the same reason.
+ * - **`year` is not a unique key for every year end.** A 364- or 371-day year drifts against
+ *   the calendar, so every label rule has year ends where two fiscal years share a label and a
+ *   calendar year names none. `"startYear"` and `"endYear"` do this for year ends near
+ *   1 January. Under `yearEndsOn: "2022-12-31"` with `"startYear"`, two fiscal years both start
+ *   in 2023, and 2020, 2025 and 2031 name none. `"majorityYear"` does it for year ends near
+ *   1 July. Under `yearEndsOn: "2026-07-01"`, 2025-07-03 to 2026-07-01 and 2026-07-02 to
+ *   2027-06-30 are both 2026. If your rule falls in such a window, key on the fiscal year's
+ *   start date, not on `year`.
  * - A `yearEndsOn` month-day that does not exist in a year follows Temporal's
  *   `overflow: "constrain"`: a February 29 rule reads February 28 in common years. A rule tied
  *   to the end of a month (the weekday nearest to, or last in, the month's final days) would
@@ -41,32 +47,36 @@ import type { FiscalCalendar } from "../../types/index.js";
  *   ends, never assumed from a table.
  * - `value` must be zoneless — an ISO date or datetime, as `isValidIsoDateLike` accepts. See
  *   `getIsoWeekDate` for why a moment is not accepted here.
- * - Returns null on invalid input, including an unrecognised pattern or a `yearEndsOn` that
- *   is not a plain ISO date. Both share the sentinel with a date that cannot be placed, so
- *   check the calendar with `isValidFiscalPattern` and `isValidDate` first to tell a
- *   misconfigured calendar apart from an unusable date.
+ * - Every date Temporal accepts gets a value, even when its fiscal year runs past
+ *   -271821-04-19 or +275760-09-13. The year, period and week are calendar arithmetic, and no
+ *   date of the fiscal year is returned.
+ * - Returns null on invalid input: a `value` that is not a zoneless ISO date, or a calendar
+ *   that is an array or has a missing or unrecognised field. Both share the sentinel, so check
+ *   the calendar with `isValidFiscalCalendar` first to tell the two apart.
  *
  * @param value zoneless ISO 8601 date or datetime string (e.g. "2024-06-15")
- * @param calendar { pattern: "4-5-4" | "4-4-5" | "5-4-4", yearEndsOn: ISO date stating the rule }
+ * @param calendar { pattern, yearEndsOn, extraWeek, yearLabel }, all required
  * @returns { year, period, week }, or null on invalid input
  *
- * @example getFiscalPeriod("2024-06-15", { pattern: "4-5-4", yearEndsOn: "2026-01-31" }) // { year: 2024, period: 5, week: 19 }
- * @example getFiscalPeriod("2024-02-04", { pattern: "4-5-4", yearEndsOn: "2026-01-31" }) // { year: 2024, period: 1, week: 1 } (NRF fiscal 2024 opens)
- * @example getFiscalPeriod("2024-01-28", { pattern: "4-5-4", yearEndsOn: "2026-01-31" }) // { year: 2023, period: 12, week: 53 } (the 53rd week of NRF fiscal 2023)
- * @example getFiscalPeriod("2024-03-31", { pattern: "4-4-5", yearEndsOn: "2026-01-31" }) // { year: 2024, period: 3, week: 9 } (the same week, a period later than 4-5-4 puts it)
- * @example getFiscalPeriod("2024-06-15", { pattern: "4-5-5", yearEndsOn: "2026-01-31" }) // null (not one of the three patterns)
- * @example getFiscalPeriod("2024-06-15T12:00:00Z", { pattern: "4-5-4", yearEndsOn: "2026-01-31" }) // null (a moment, not a calendar date)
- * @example getFiscalPeriod("invalid", { pattern: "4-5-4", yearEndsOn: "2026-01-31" }) // null
+ * @example getFiscalPeriod("2024-06-15", { pattern: "4-5-4", yearEndsOn: "2026-01-31", extraWeek: "lastPeriod", yearLabel: "startYear" }) // { year: 2024, period: 5, week: 19 }
+ * @example getFiscalPeriod("2024-02-04", { pattern: "4-5-4", yearEndsOn: "2026-01-31", extraWeek: "lastPeriod", yearLabel: "startYear" }) // { year: 2024, period: 1, week: 1 } (NRF fiscal 2024 opens)
+ * @example getFiscalPeriod("2024-01-28", { pattern: "4-5-4", yearEndsOn: "2026-01-31", extraWeek: "lastPeriod", yearLabel: "startYear" }) // { year: 2023, period: 12, week: 53 } (the 53rd week of NRF fiscal 2023)
+ * @example getFiscalPeriod("2024-01-28", { pattern: "4-5-4", yearEndsOn: "2026-01-31", extraWeek: "lastPeriod", yearLabel: "endYear" }) // { year: 2024, period: 12, week: 53 } (the same week, named by the year it ends in)
+ * @example getFiscalPeriod("2024-03-31", { pattern: "4-4-5", yearEndsOn: "2026-01-31", extraWeek: "lastPeriod", yearLabel: "startYear" }) // { year: 2024, period: 3, week: 9 }
+ * @example getFiscalPeriod("2025-02-01", { pattern: "4-4-5", yearEndsOn: "2022-12-31", extraWeek: "firstPeriod", yearLabel: "majorityYear" }) // { year: 2025, period: 1, week: 5 } (ONS 2025: a five-week January)
+ * @example getFiscalPeriod("2024-12-29", { pattern: "4-4-5", yearEndsOn: "2022-12-31", extraWeek: "firstPeriod", yearLabel: "majorityYear" }) // { year: 2025, period: 1, week: 1 } (ONS 2025 opens in December 2024)
+ * @example getFiscalPeriod("+275760-09-13", { pattern: "4-5-4", yearEndsOn: "2026-01-31", extraWeek: "lastPeriod", yearLabel: "startYear" }) // { year: 275760, period: 8, week: 32 } (Temporal's last date; its fiscal year closes past it)
+ * @example getFiscalPeriod("2024-06-15", { pattern: "4-5-5", yearEndsOn: "2026-01-31", extraWeek: "lastPeriod", yearLabel: "startYear" }) // null (not one of the three patterns)
+ * @example getFiscalPeriod("2024-06-15", { pattern: "4-5-4", yearEndsOn: "2026-01-31", extraWeek: "lastPeriod" }) // null (no yearLabel)
+ * @example getFiscalPeriod("2024-06-15T12:00:00Z", { pattern: "4-5-4", yearEndsOn: "2026-01-31", extraWeek: "lastPeriod", yearLabel: "startYear" }) // null (a moment, not a calendar date)
  */
 export declare function getFiscalPeriod(value: string, calendar: FiscalCalendar): {
-    /**
-     * The calendar year the fiscal year starts in, not the year it ends in. Two consecutive fiscal
-     * years can share this label when `yearEndsOn` sits near 1 January.
-     */
+    /** The calendar year that names the fiscal year, chosen by `calendar.yearLabel`. */
     year: number;
     /**
      * The period of the fiscal year, 1 through 12. Each period is four or five weeks long as
-     * `calendar.pattern` sets, and a 53rd week belongs to period 12.
+     * `calendar.pattern` sets, and a 53rd week belongs to period 1 or period 12, as
+     * `calendar.extraWeek` says.
      */
     period: number;
     /**

package/dist/calendar/calculate/getFiscalPeriod.js

@@ -1,7 +1,7 @@
-import { Temporal } from "@js-temporal/polyfill";
-import { fiscalPeriodOfWeek, fiscalYearOf, zonelessCalendarDate, } from "../../internal/index.js";
-import { isValidDate } from "../../plain/validate/index.js";
-import { isValidFiscalPattern } from "../validate/index.js";
+import { Temporal } from "../../internal/temporal.js";
+import { fiscalPeriodOfWeek, fiscalYearLabel, fiscalYearOf, gregorianCycleShift, zonelessCalendarDate, } from "../../internal/index.js";
+import { isObject } from "../../internal/isObject.js";
+import { isValidFiscalCalendar } from "../validate/index.js";
 /** Days in a fiscal week. */
 const DAYS_PER_WEEK = 7;
 /**
@@ -12,31 +12,37 @@ const DAYS_PER_WEEK = 7;
  * insertion fall out of `calendar` — nothing here is bundled, because there is no single
  * correct retail calendar.
  *
- * - `calendar.pattern` is the weeks-per-period shape of a quarter: `"4-5-4"` (the NRF retail
- *   standard), `"4-4-5"` or `"5-4-4"`. Four quarters of 13 weeks make the 52-week year.
+ * - `calendar.pattern` is the weeks-per-period shape of a quarter: `"4-5-4"`, `"4-4-5"` or
+ *   `"5-4-4"`. Four quarters of 13 weeks make the 52-week year.
  * - **`calendar.yearEndsOn` states the year-end *rule*, by example, not one year's end.**
  *   Fiscal years end on that date's weekday, on the occurrence nearest that date's month and
- *   day. The NRF's published rule — "the Saturday nearest to January 31"
- *   ([NRF 4-5-4 calendar](https://nrf.com/resources/4-5-4-calendar)) — is `"2026-01-31"`, a
- *   Saturday falling exactly on January 31. Passing a published year end from a 53-week year
- *   instead (`"2024-02-03"`) states a different rule, because that date sits three days off
- *   the target the rule is centred on, and yields a different, self-consistent calendar.
- * - Weeks are numbered through the fiscal year as the NRF publishes them. A 53rd week is
- *   appended to period 12 — the NRF adds it "to the end of the calendar" — which makes a 4-5-4
- *   year's final quarter 4-5-5.
- * - The `year` label follows the NRF: fiscal 2023 runs 2023-01-29 to 2024-02-03. Organisations
- *   labelling by the end year should add one.
- * - **`year` is not a unique key for a rule anchored near 1 January.** A 52/53-week year is
- *   364 or 371 days, so it drifts against the calendar, and no label taken from a calendar
- *   year survives that for every anchor. Under `yearEndsOn: "2022-12-31"` — the Saturday
- *   nearest to 31 December — two consecutive fiscal years both start in 2023 and share the
- *   label, and 2020, 2025 and 2031 label no fiscal year at all. Grouping by `year` there
- *   merges 104 weeks and drops a year. `"2027-01-02"` states a different rule, the Saturday
- *   nearest to 2 January: it too gives 2023 twice, merging 105 weeks, and skips 2018, 2024
- *   and 2029. January/February anchors like the NRF's
- *   are unaffected. If your rule sits near a year boundary, key on the fiscal year's own start
- *   date — which `yearEndsOn` determines, and which is yours to enumerate — not on `year`.
- *   GMT does not invent a label the inputs do not fix.
+ *   day. One published 4-5-4 example (NRF, US) adds a 53rd week when "there are four or more
+ *   days left in January" ([NRF 4-5-4 calendar](https://nrf.com/resources/4-5-4-calendar)),
+ *   which puts its year end on the Saturday nearest January 31. As `yearEndsOn` that is
+ *   `"2026-01-31"`, a Saturday falling exactly on January 31. Passing a published year end
+ *   from a 53-week year instead (`"2024-02-03"`) states a different rule, because that date
+ *   sits three days off the target the rule is centred on, and yields a different,
+ *   self-consistent calendar.
+ * - IFRS 18 ¶29 (formerly IAS 1 ¶37; IFRS 18 applies to reporting periods beginning on or
+ *   after 2027-01-01) does not preclude reporting for a 52-week period, and a 53-week year
+ *   follows from it. No international standard says where the 53rd week goes or which
+ *   calendar year names the fiscal year, and published calendars disagree on both. So
+ *   `calendar.extraWeek` and `calendar.yearLabel` are required, and there is no default.
+ * - `calendar.extraWeek` is the period a 53rd week is added to: `"firstPeriod"` (ONS, UK: "a
+ *   five week January") or `"lastPeriod"` (NRF, US: "to the end of the calendar").
+ * - `calendar.yearLabel` names the fiscal year: `"startYear"` (NRF, US), `"endYear"`, the
+ *   year its last day falls in, or `"majorityYear"`, the calendar year holding the most days
+ *   (ONS, UK). IFRS 18 ¶27(c) (formerly IAS 1 ¶51(c)) lets a reporting period be identified
+ *   by the date it ends, which supports `"endYear"`. GMT rule: a 182/182 split goes to the
+ *   end year, for the same reason.
+ * - **`year` is not a unique key for every year end.** A 364- or 371-day year drifts against
+ *   the calendar, so every label rule has year ends where two fiscal years share a label and a
+ *   calendar year names none. `"startYear"` and `"endYear"` do this for year ends near
+ *   1 January. Under `yearEndsOn: "2022-12-31"` with `"startYear"`, two fiscal years both start
+ *   in 2023, and 2020, 2025 and 2031 name none. `"majorityYear"` does it for year ends near
+ *   1 July. Under `yearEndsOn: "2026-07-01"`, 2025-07-03 to 2026-07-01 and 2026-07-02 to
+ *   2027-06-30 are both 2026. If your rule falls in such a window, key on the fiscal year's
+ *   start date, not on `year`.
  * - A `yearEndsOn` month-day that does not exist in a year follows Temporal's
  *   `overflow: "constrain"`: a February 29 rule reads February 28 in common years. A rule tied
  *   to the end of a month (the weekday nearest to, or last in, the month's final days) would
@@ -46,48 +52,63 @@ const DAYS_PER_WEEK = 7;
  *   ends, never assumed from a table.
  * - `value` must be zoneless — an ISO date or datetime, as `isValidIsoDateLike` accepts. See
  *   `getIsoWeekDate` for why a moment is not accepted here.
- * - Returns null on invalid input, including an unrecognised pattern or a `yearEndsOn` that
- *   is not a plain ISO date. Both share the sentinel with a date that cannot be placed, so
- *   check the calendar with `isValidFiscalPattern` and `isValidDate` first to tell a
- *   misconfigured calendar apart from an unusable date.
+ * - Every date Temporal accepts gets a value, even when its fiscal year runs past
+ *   -271821-04-19 or +275760-09-13. The year, period and week are calendar arithmetic, and no
+ *   date of the fiscal year is returned.
+ * - Returns null on invalid input: a `value` that is not a zoneless ISO date, or a calendar
+ *   that is an array or has a missing or unrecognised field. Both share the sentinel, so check
+ *   the calendar with `isValidFiscalCalendar` first to tell the two apart.
  *
  * @param value zoneless ISO 8601 date or datetime string (e.g. "2024-06-15")
- * @param calendar { pattern: "4-5-4" | "4-4-5" | "5-4-4", yearEndsOn: ISO date stating the rule }
+ * @param calendar { pattern, yearEndsOn, extraWeek, yearLabel }, all required
  * @returns { year, period, week }, or null on invalid input
  *
- * @example getFiscalPeriod("2024-06-15", { pattern: "4-5-4", yearEndsOn: "2026-01-31" }) // { year: 2024, period: 5, week: 19 }
- * @example getFiscalPeriod("2024-02-04", { pattern: "4-5-4", yearEndsOn: "2026-01-31" }) // { year: 2024, period: 1, week: 1 } (NRF fiscal 2024 opens)
- * @example getFiscalPeriod("2024-01-28", { pattern: "4-5-4", yearEndsOn: "2026-01-31" }) // { year: 2023, period: 12, week: 53 } (the 53rd week of NRF fiscal 2023)
- * @example getFiscalPeriod("2024-03-31", { pattern: "4-4-5", yearEndsOn: "2026-01-31" }) // { year: 2024, period: 3, week: 9 } (the same week, a period later than 4-5-4 puts it)
- * @example getFiscalPeriod("2024-06-15", { pattern: "4-5-5", yearEndsOn: "2026-01-31" }) // null (not one of the three patterns)
- * @example getFiscalPeriod("2024-06-15T12:00:00Z", { pattern: "4-5-4", yearEndsOn: "2026-01-31" }) // null (a moment, not a calendar date)
- * @example getFiscalPeriod("invalid", { pattern: "4-5-4", yearEndsOn: "2026-01-31" }) // null
+ * @example getFiscalPeriod("2024-06-15", { pattern: "4-5-4", yearEndsOn: "2026-01-31", extraWeek: "lastPeriod", yearLabel: "startYear" }) // { year: 2024, period: 5, week: 19 }
+ * @example getFiscalPeriod("2024-02-04", { pattern: "4-5-4", yearEndsOn: "2026-01-31", extraWeek: "lastPeriod", yearLabel: "startYear" }) // { year: 2024, period: 1, week: 1 } (NRF fiscal 2024 opens)
+ * @example getFiscalPeriod("2024-01-28", { pattern: "4-5-4", yearEndsOn: "2026-01-31", extraWeek: "lastPeriod", yearLabel: "startYear" }) // { year: 2023, period: 12, week: 53 } (the 53rd week of NRF fiscal 2023)
+ * @example getFiscalPeriod("2024-01-28", { pattern: "4-5-4", yearEndsOn: "2026-01-31", extraWeek: "lastPeriod", yearLabel: "endYear" }) // { year: 2024, period: 12, week: 53 } (the same week, named by the year it ends in)
+ * @example getFiscalPeriod("2024-03-31", { pattern: "4-4-5", yearEndsOn: "2026-01-31", extraWeek: "lastPeriod", yearLabel: "startYear" }) // { year: 2024, period: 3, week: 9 }
+ * @example getFiscalPeriod("2025-02-01", { pattern: "4-4-5", yearEndsOn: "2022-12-31", extraWeek: "firstPeriod", yearLabel: "majorityYear" }) // { year: 2025, period: 1, week: 5 } (ONS 2025: a five-week January)
+ * @example getFiscalPeriod("2024-12-29", { pattern: "4-4-5", yearEndsOn: "2022-12-31", extraWeek: "firstPeriod", yearLabel: "majorityYear" }) // { year: 2025, period: 1, week: 1 } (ONS 2025 opens in December 2024)
+ * @example getFiscalPeriod("+275760-09-13", { pattern: "4-5-4", yearEndsOn: "2026-01-31", extraWeek: "lastPeriod", yearLabel: "startYear" }) // { year: 275760, period: 8, week: 32 } (Temporal's last date; its fiscal year closes past it)
+ * @example getFiscalPeriod("2024-06-15", { pattern: "4-5-5", yearEndsOn: "2026-01-31", extraWeek: "lastPeriod", yearLabel: "startYear" }) // null (not one of the three patterns)
+ * @example getFiscalPeriod("2024-06-15", { pattern: "4-5-4", yearEndsOn: "2026-01-31", extraWeek: "lastPeriod" }) // null (no yearLabel)
+ * @example getFiscalPeriod("2024-06-15T12:00:00Z", { pattern: "4-5-4", yearEndsOn: "2026-01-31", extraWeek: "lastPeriod", yearLabel: "startYear" }) // null (a moment, not a calendar date)
  */
 export function getFiscalPeriod(value, calendar) {
     try {
-        const pattern = calendar?.pattern;
-        const yearEndsOn = calendar?.yearEndsOn;
-        if (!isValidFiscalPattern(pattern) || !isValidDate(yearEndsOn)) {
+        // An array is refused before its fields are copied, as isValidFiscalCalendar refuses it.
+        if (!isObject(calendar) || Array.isArray(calendar))
+            return null;
+        // Read each field once: a getter could answer differently on a second read, and the
+        // value validated must be the value used.
+        const fields = {
+            pattern: calendar.pattern,
+            yearEndsOn: calendar.yearEndsOn,
+            extraWeek: calendar.extraWeek,
+            yearLabel: calendar.yearLabel,
+        };
+        if (!isValidFiscalCalendar(fields))
             return null;
-        }
         const date = zonelessCalendarDate(value);
         if (!date)
             return null;
-        try {
-            const fiscalYear = fiscalYearOf(date, Temporal.PlainDate.from(yearEndsOn));
-            if (!fiscalYear)
-                return null;
-            const { start, weeks } = fiscalYear;
-            const week = Math.floor(start.until(date, { largestUnit: "day" }).days / DAYS_PER_WEEK) + 1;
-            return {
-                year: start.year,
-                period: fiscalPeriodOfWeek(week, weeks, pattern),
-                week,
-            };
-        }
-        catch {
+        // A fiscal year near Temporal's first or last date can run past it. Its year, period and
+        // week are calendar arithmetic, so work them in the year 2000 to 2399 with the same leap
+        // pattern, then move the year back. Period and week do not move.
+        const shift = gregorianCycleShift(date.year);
+        const local = date.with({ year: date.year - shift });
+        const fiscalYear = fiscalYearOf(local, Temporal.PlainDate.from(fields.yearEndsOn));
+        if (!fiscalYear)
             return null;
-        }
+        const { start, weeks } = fiscalYear;
+        const end = start.add({ days: weeks * DAYS_PER_WEEK - 1 });
+        const week = Math.floor(start.until(local, { largestUnit: "day" }).days / DAYS_PER_WEEK) + 1;
+        return {
+            year: fiscalYearLabel(start, end, fields.yearLabel) + shift,
+            period: fiscalPeriodOfWeek(week, weeks, fields.pattern, fields.extraWeek),
+            week,
+        };
     }
     catch {
         // Never throws (Core Rule 3): a hostile

package/dist/calendar/calculate/getQuarter.d.ts

@@ -1,48 +1,53 @@
+import type { FiscalYearLabel } from "../../types/index.js";
 /**
  * Return the quarter `value` falls in, as a year and a quarter number.
  *
  * - With no options these are the calendar quarters: Q1 is January to March, and `year` is
  *   the calendar year.
- * - Labelling a fiscal year by the calendar year it starts in matches the NRF retail
- *   convention `getFiscalPeriod` uses. Organisations that label a fiscal year by the calendar
- *   year it *ends* in — for a fiscal year that starts in October, FY2025 begins in October
- *   2024 — should add one to `year`.
+ * - With `options`, these are fiscal quarters. The fiscal year starts on day 1 of
+ *   `fiscalYearStartMonth`, and `yearLabel` names it: `"startYear"`, `"endYear"`, or
+ *   `"majorityYear"` (the calendar year holding the most of its days). Both are required, and
+ *   there is no default. Start months 1 to 7 put most days in the start year, and 8 to 12 put
+ *   most in the end year.
  * - `value` must be zoneless — an ISO date or datetime, as `isValidIsoDateLike` accepts. See
  *   `getIsoWeekDate` for why a moment is not accepted here.
- * - Returns null on invalid input, including a `fiscalYearStartMonth` that is not an integer
- *   from 1 to 12.
+ * - Returns null on invalid input, including `options` without both fields, a
+ *   `fiscalYearStartMonth` that is not an integer from 1 to 12, or an unrecognised `yearLabel`.
  *
  * @param value zoneless ISO 8601 date or datetime string (e.g. "2024-06-15")
- * @param optionsArg The month the fiscal year starts in
+ * @param optionsArg The fiscal year's start month and the rule that names it
  * @returns { year, quarter }, or null on invalid input
  *
  * @example getQuarter("2024-06-15") // { year: 2024, quarter: 2 }
  * @example getQuarter("2024-10-01") // { year: 2024, quarter: 4 }
- * @example getQuarter("2024-06-15", { fiscalYearStartMonth: 1 }) // { year: 2024, quarter: 2 } (the default, stated)
- * @example getQuarter("2024-04-01", { fiscalYearStartMonth: 4 }) // { year: 2024, quarter: 1 }
- * @example getQuarter("2024-03-31", { fiscalYearStartMonth: 4 }) // { year: 2023, quarter: 4 } (the previous fiscal year)
- * @example getQuarter("2024-06-15", { fiscalYearStartMonth: 13 }) // null
+ * @example getQuarter("2024-04-01", { fiscalYearStartMonth: 4, yearLabel: "startYear" }) // { year: 2024, quarter: 1 }
+ * @example getQuarter("2024-03-31", { fiscalYearStartMonth: 4, yearLabel: "startYear" }) // { year: 2023, quarter: 4 } (the previous fiscal year)
+ * @example getQuarter("2024-03-31", { fiscalYearStartMonth: 4, yearLabel: "endYear" }) // { year: 2024, quarter: 4 }
+ * @example getQuarter("2023-10-15", { fiscalYearStartMonth: 7, yearLabel: "endYear" }) // { year: 2024, quarter: 2 }
+ * @example getQuarter("2023-10-15", { fiscalYearStartMonth: 7, yearLabel: "majorityYear" }) // { year: 2023, quarter: 2 } (July to December is 184 of its days)
+ * @example getQuarter("2024-10-01", { fiscalYearStartMonth: 10, yearLabel: "majorityYear" }) // { year: 2025, quarter: 1 }
+ * @example getQuarter("2024-06-15", { fiscalYearStartMonth: 4 }) // null (no yearLabel)
+ * @example getQuarter("2024-06-15", { fiscalYearStartMonth: 13, yearLabel: "startYear" }) // null
  * @example getQuarter("2024-06-15T12:00:00Z") // null (a moment, not a calendar date)
  * @example getQuarter("invalid") // null
  */
 export declare function getQuarter(value: string, optionsArg?: {
     /**
-     * The month the year starts in, 1 (January) through 12, which makes the quarters fiscal
-     * quarters. A date before it belongs to the previous fiscal year, so with `4` the date
-     * `"2024-03-31"` is Q4 of 2023.
-     *
-     * @defaultValue `1`
+     * The month the fiscal year starts in, 1 (January) through 12. A date before it belongs to
+     * the previous fiscal year, so with `4` the date `"2024-03-31"` is in that year's Q4.
      */
-    fiscalYearStartMonth?: number;
+    fiscalYearStartMonth: number;
+    /** The calendar year that names a fiscal year. See `FiscalYearLabel`. */
+    yearLabel: FiscalYearLabel;
 }): {
     /**
-     * The year the quarter belongs to. With `fiscalYearStartMonth` set, it is the calendar year the
-     * fiscal year starts in, so a date before the start month reports the previous year.
+     * The year that names the quarter's year: the calendar year with no `options`, otherwise the
+     * one `yearLabel` picks.
      */
     year: number;
     /**
-     * The quarter of that year, 1 through 4. Quarter 1 begins in the `fiscalYearStartMonth` month,
-     * which is January by default.
+     * The quarter of that year, 1 through 4. Quarter 1 begins in January with no `options`, and
+     * in the `fiscalYearStartMonth` month otherwise.
      */
     quarter: number;
 } | null;

package/dist/calendar/calculate/getQuarter.js

@@ -1,6 +1,7 @@
-import { zonelessCalendarDate } from "../../internal/index.js";
+import { Temporal } from "../../internal/temporal.js";
+import { fiscalYearLabel, gregorianCycleShift, zonelessCalendarDate, } from "../../internal/index.js";
 import { isOptionsArgument } from "../../internal/isObject.js";
-import { optionOrDefault } from "../../internal/optionOrDefault.js";
+import { isValidFiscalYearLabel } from "../validate/index.js";
 /** Months in a quarter. */
 const MONTHS_PER_QUARTER = 3;
 /** Months in a year. */
@@ -10,45 +11,73 @@ const MONTHS_PER_YEAR = 12;
  *
  * - With no options these are the calendar quarters: Q1 is January to March, and `year` is
  *   the calendar year.
- * - Labelling a fiscal year by the calendar year it starts in matches the NRF retail
- *   convention `getFiscalPeriod` uses. Organisations that label a fiscal year by the calendar
- *   year it *ends* in — for a fiscal year that starts in October, FY2025 begins in October
- *   2024 — should add one to `year`.
+ * - With `options`, these are fiscal quarters. The fiscal year starts on day 1 of
+ *   `fiscalYearStartMonth`, and `yearLabel` names it: `"startYear"`, `"endYear"`, or
+ *   `"majorityYear"` (the calendar year holding the most of its days). Both are required, and
+ *   there is no default. Start months 1 to 7 put most days in the start year, and 8 to 12 put
+ *   most in the end year.
  * - `value` must be zoneless — an ISO date or datetime, as `isValidIsoDateLike` accepts. See
  *   `getIsoWeekDate` for why a moment is not accepted here.
- * - Returns null on invalid input, including a `fiscalYearStartMonth` that is not an integer
- *   from 1 to 12.
+ * - Returns null on invalid input, including `options` without both fields, a
+ *   `fiscalYearStartMonth` that is not an integer from 1 to 12, or an unrecognised `yearLabel`.
  *
  * @param value zoneless ISO 8601 date or datetime string (e.g. "2024-06-15")
- * @param optionsArg The month the fiscal year starts in
+ * @param optionsArg The fiscal year's start month and the rule that names it
  * @returns { year, quarter }, or null on invalid input
  *
  * @example getQuarter("2024-06-15") // { year: 2024, quarter: 2 }
  * @example getQuarter("2024-10-01") // { year: 2024, quarter: 4 }
- * @example getQuarter("2024-06-15", { fiscalYearStartMonth: 1 }) // { year: 2024, quarter: 2 } (the default, stated)
- * @example getQuarter("2024-04-01", { fiscalYearStartMonth: 4 }) // { year: 2024, quarter: 1 }
- * @example getQuarter("2024-03-31", { fiscalYearStartMonth: 4 }) // { year: 2023, quarter: 4 } (the previous fiscal year)
- * @example getQuarter("2024-06-15", { fiscalYearStartMonth: 13 }) // null
+ * @example getQuarter("2024-04-01", { fiscalYearStartMonth: 4, yearLabel: "startYear" }) // { year: 2024, quarter: 1 }
+ * @example getQuarter("2024-03-31", { fiscalYearStartMonth: 4, yearLabel: "startYear" }) // { year: 2023, quarter: 4 } (the previous fiscal year)
+ * @example getQuarter("2024-03-31", { fiscalYearStartMonth: 4, yearLabel: "endYear" }) // { year: 2024, quarter: 4 }
+ * @example getQuarter("2023-10-15", { fiscalYearStartMonth: 7, yearLabel: "endYear" }) // { year: 2024, quarter: 2 }
+ * @example getQuarter("2023-10-15", { fiscalYearStartMonth: 7, yearLabel: "majorityYear" }) // { year: 2023, quarter: 2 } (July to December is 184 of its days)
+ * @example getQuarter("2024-10-01", { fiscalYearStartMonth: 10, yearLabel: "majorityYear" }) // { year: 2025, quarter: 1 }
+ * @example getQuarter("2024-06-15", { fiscalYearStartMonth: 4 }) // null (no yearLabel)
+ * @example getQuarter("2024-06-15", { fiscalYearStartMonth: 13, yearLabel: "startYear" }) // null
  * @example getQuarter("2024-06-15T12:00:00Z") // null (a moment, not a calendar date)
  * @example getQuarter("invalid") // null
  */
 export function getQuarter(value, optionsArg) {
     try {
-        if (!isOptionsArgument(optionsArg)) {
-            return null;
+        if (optionsArg === undefined) {
+            const date = zonelessCalendarDate(value);
+            if (!date)
+                return null;
+            return {
+                year: date.year,
+                quarter: Math.floor((date.month - 1) / MONTHS_PER_QUARTER) + 1,
+            };
         }
-        const fiscalYearStartMonth = optionOrDefault(optionsArg?.fiscalYearStartMonth, 1);
-        if (!Number.isInteger(fiscalYearStartMonth) ||
+        if (!isOptionsArgument(optionsArg))
+            return null;
+        // Read each option once: the value validated must be the value used.
+        const fiscalYearStartMonth = optionsArg.fiscalYearStartMonth;
+        const yearLabel = optionsArg.yearLabel;
+        if (typeof fiscalYearStartMonth !== "number" ||
+            !Number.isInteger(fiscalYearStartMonth) ||
             fiscalYearStartMonth < 1 ||
-            fiscalYearStartMonth > MONTHS_PER_YEAR) {
+            fiscalYearStartMonth > MONTHS_PER_YEAR ||
+            !isValidFiscalYearLabel(yearLabel)) {
             return null;
         }
         const date = zonelessCalendarDate(value);
         if (!date)
             return null;
+        const startYear = date.month < fiscalYearStartMonth ? date.year - 1 : date.year;
+        // A fiscal year near Temporal's first or last date can run past it. Its label is calendar
+        // arithmetic, so build it in the year 2000 to 2399 with the same leap pattern, then move
+        // the label back.
+        const shift = gregorianCycleShift(startYear);
+        const start = Temporal.PlainDate.from({
+            year: startYear - shift,
+            month: fiscalYearStartMonth,
+            day: 1,
+        });
+        const end = start.add({ years: 1 }).subtract({ days: 1 });
         const monthsIntoYear = (date.month - fiscalYearStartMonth + MONTHS_PER_YEAR) % MONTHS_PER_YEAR;
         return {
-            year: date.month < fiscalYearStartMonth ? date.year - 1 : date.year,
+            year: fiscalYearLabel(start, end, yearLabel) + shift,
             quarter: Math.floor(monthsIntoYear / MONTHS_PER_QUARTER) + 1,
         };
     }

package/dist/calendar/hours/addOperatingTime.d.ts

@@ -30,9 +30,9 @@ import type { Disambiguation, OperatingSchedule } from "../../types/index.js";
  * @param optionsArg How far the search goes, and how a window edge on a clock change is resolved
  * @returns UTC instant string ending in "Z", or "" when past the horizon or on invalid input
  *
- * @example addOperatingTime("2024-06-14T20:00:00Z", "PT2H", { timeZone: "America/New_York", weekly: { 1: [{ from: "09:00", to: "17:00" }], 5: [{ from: "09:00", to: "17:00" }] } }) // "2024-06-17T14:00:00Z" — Friday 16:00 to Monday 10:00 local
- * @example addOperatingTime("2024-06-14T20:00:00Z", "PT1H", { timeZone: "America/New_York", weekly: { 5: [{ from: "09:00", to: "17:00" }] } }) // "2024-06-14T21:00:00Z" — due at closing, not at the next opening
- * @example addOperatingTime("2024-06-14T20:00:00Z", "PT2H", { timeZone: "America/New_York", weekly: { 1: [{ from: "09:00", to: "17:00" }], 5: [{ from: "09:00", to: "17:00" }] } }, { within: "P1D" }) // "" — past the horizon
+ * @example addOperatingTime("2024-06-14T15:00:00Z", "PT2H", { timeZone: "Europe/London", weekly: { 1: [{ from: "09:00", to: "17:00" }], 5: [{ from: "09:00", to: "17:00" }] } }) // "2024-06-17T09:00:00Z" — Friday 16:00 to Monday 10:00 local
+ * @example addOperatingTime("2024-06-14T15:00:00Z", "PT1H", { timeZone: "Europe/London", weekly: { 5: [{ from: "09:00", to: "17:00" }] } }) // "2024-06-14T16:00:00Z" — due at closing, not at the next opening
+ * @example addOperatingTime("2024-06-14T15:00:00Z", "PT2H", { timeZone: "Europe/London", weekly: { 1: [{ from: "09:00", to: "17:00" }], 5: [{ from: "09:00", to: "17:00" }] } }, { within: "P1D" }) // "" — past the horizon
  * @example addOperatingTime("2024-06-15T12:00:00Z", "PT0S", { timeZone: "UTC", weekly: {} }) // "2024-06-15T12:00:00Z"
  * @example addOperatingTime("2024-06-14T20:00:00Z", "P1D", { timeZone: "UTC", weekly: { 5: [{ from: "09:00", to: "17:00" }] } }) // "" — days are not open time
  * @example addOperatingTime("2024-06-14T20:00:00Z", "-PT1H", { timeZone: "UTC", weekly: { 5: [{ from: "09:00", to: "17:00" }] } }) // ""

package/dist/calendar/hours/addOperatingTime.js

@@ -31,9 +31,9 @@ import { instantAfterOpenTime, instantText, parseOpenTimeAmount, parseOperatingS
  * @param optionsArg How far the search goes, and how a window edge on a clock change is resolved
  * @returns UTC instant string ending in "Z", or "" when past the horizon or on invalid input
  *
- * @example addOperatingTime("2024-06-14T20:00:00Z", "PT2H", { timeZone: "America/New_York", weekly: { 1: [{ from: "09:00", to: "17:00" }], 5: [{ from: "09:00", to: "17:00" }] } }) // "2024-06-17T14:00:00Z" — Friday 16:00 to Monday 10:00 local
- * @example addOperatingTime("2024-06-14T20:00:00Z", "PT1H", { timeZone: "America/New_York", weekly: { 5: [{ from: "09:00", to: "17:00" }] } }) // "2024-06-14T21:00:00Z" — due at closing, not at the next opening
- * @example addOperatingTime("2024-06-14T20:00:00Z", "PT2H", { timeZone: "America/New_York", weekly: { 1: [{ from: "09:00", to: "17:00" }], 5: [{ from: "09:00", to: "17:00" }] } }, { within: "P1D" }) // "" — past the horizon
+ * @example addOperatingTime("2024-06-14T15:00:00Z", "PT2H", { timeZone: "Europe/London", weekly: { 1: [{ from: "09:00", to: "17:00" }], 5: [{ from: "09:00", to: "17:00" }] } }) // "2024-06-17T09:00:00Z" — Friday 16:00 to Monday 10:00 local
+ * @example addOperatingTime("2024-06-14T15:00:00Z", "PT1H", { timeZone: "Europe/London", weekly: { 5: [{ from: "09:00", to: "17:00" }] } }) // "2024-06-14T16:00:00Z" — due at closing, not at the next opening
+ * @example addOperatingTime("2024-06-14T15:00:00Z", "PT2H", { timeZone: "Europe/London", weekly: { 1: [{ from: "09:00", to: "17:00" }], 5: [{ from: "09:00", to: "17:00" }] } }, { within: "P1D" }) // "" — past the horizon
  * @example addOperatingTime("2024-06-15T12:00:00Z", "PT0S", { timeZone: "UTC", weekly: {} }) // "2024-06-15T12:00:00Z"
  * @example addOperatingTime("2024-06-14T20:00:00Z", "P1D", { timeZone: "UTC", weekly: { 5: [{ from: "09:00", to: "17:00" }] } }) // "" — days are not open time
  * @example addOperatingTime("2024-06-14T20:00:00Z", "-PT1H", { timeZone: "UTC", weekly: { 5: [{ from: "09:00", to: "17:00" }] } }) // ""

package/dist/calendar/hours/isOpenAt.d.ts

@@ -24,10 +24,10 @@ import type { Disambiguation, OperatingSchedule } from "../../types/index.js";
  * @param optionsArg How a window edge on a clock change is resolved
  * @returns true when open at that instant, or false when closed or on invalid input
  *
- * @example isOpenAt("2024-06-17T14:00:00Z", { timeZone: "America/New_York", weekly: { 1: [{ from: "09:00", to: "17:00" }] } }) // true — Monday 10:00 local
- * @example isOpenAt("2024-06-17T21:00:00Z", { timeZone: "America/New_York", weekly: { 1: [{ from: "09:00", to: "17:00" }] } }) // false — 17:00 local, the window has closed
+ * @example isOpenAt("2024-06-17T01:00:00Z", { timeZone: "Asia/Tokyo", weekly: { 1: [{ from: "09:00", to: "17:00" }] } }) // true — Monday 10:00 local
+ * @example isOpenAt("2024-06-17T08:00:00Z", { timeZone: "Asia/Tokyo", weekly: { 1: [{ from: "09:00", to: "17:00" }] } }) // false — 17:00 local, the window has closed
  * @example isOpenAt("2024-06-15T01:00:00Z", { timeZone: "UTC", weekly: { 5: [{ from: "23:00", to: "06:00" }] } }) // true — Friday's night window, on Saturday morning
- * @example isOpenAt("2024-07-04T14:00:00Z", { timeZone: "America/New_York", weekly: { 4: [{ from: "09:00", to: "17:00" }] }, holidays: ["2024-07-04"] }) // false — a holiday
+ * @example isOpenAt("2024-07-04T08:00:00Z", { timeZone: "Africa/Kigali", weekly: { 4: [{ from: "09:00", to: "17:00" }] }, holidays: ["2024-07-04"] }) // false — a holiday
  * @example isOpenAt("2024-06-17T14:00:00", { timeZone: "UTC", weekly: { 1: [{ from: "09:00", to: "17:00" }] } }) // false — no offset, not an instant
  * @example isOpenAt("1970-01-01T08:44:30Z", { timeZone: "-00:44:30", weekly: { 4: [{ from: "08:00", to: "17:00" }] } }) // true (08:00 at a stored offset with seconds)
  */

package/dist/calendar/hours/isOpenAt.js

@@ -25,10 +25,10 @@ import { firstOpenInstant, parseOperatingSchedule, parseScheduleDisambiguation,
  * @param optionsArg How a window edge on a clock change is resolved
  * @returns true when open at that instant, or false when closed or on invalid input
  *
- * @example isOpenAt("2024-06-17T14:00:00Z", { timeZone: "America/New_York", weekly: { 1: [{ from: "09:00", to: "17:00" }] } }) // true — Monday 10:00 local
- * @example isOpenAt("2024-06-17T21:00:00Z", { timeZone: "America/New_York", weekly: { 1: [{ from: "09:00", to: "17:00" }] } }) // false — 17:00 local, the window has closed
+ * @example isOpenAt("2024-06-17T01:00:00Z", { timeZone: "Asia/Tokyo", weekly: { 1: [{ from: "09:00", to: "17:00" }] } }) // true — Monday 10:00 local
+ * @example isOpenAt("2024-06-17T08:00:00Z", { timeZone: "Asia/Tokyo", weekly: { 1: [{ from: "09:00", to: "17:00" }] } }) // false — 17:00 local, the window has closed
  * @example isOpenAt("2024-06-15T01:00:00Z", { timeZone: "UTC", weekly: { 5: [{ from: "23:00", to: "06:00" }] } }) // true — Friday's night window, on Saturday morning
- * @example isOpenAt("2024-07-04T14:00:00Z", { timeZone: "America/New_York", weekly: { 4: [{ from: "09:00", to: "17:00" }] }, holidays: ["2024-07-04"] }) // false — a holiday
+ * @example isOpenAt("2024-07-04T08:00:00Z", { timeZone: "Africa/Kigali", weekly: { 4: [{ from: "09:00", to: "17:00" }] }, holidays: ["2024-07-04"] }) // false — a holiday
  * @example isOpenAt("2024-06-17T14:00:00", { timeZone: "UTC", weekly: { 1: [{ from: "09:00", to: "17:00" }] } }) // false — no offset, not an instant
  * @example isOpenAt("1970-01-01T08:44:30Z", { timeZone: "-00:44:30", weekly: { 4: [{ from: "08:00", to: "17:00" }] } }) // true (08:00 at a stored offset with seconds)
  */

package/dist/calendar/hours/nextCloseAt.d.ts

@@ -26,8 +26,8 @@ import type { Disambiguation, OperatingSchedule } from "../../types/index.js";
  * @param optionsArg How far the search goes, and how a window edge on a clock change is resolved
  * @returns UTC instant string ending in "Z", or "" when none within the horizon or on invalid input
  *
- * @example nextCloseAt("2024-06-17T14:00:00Z", { timeZone: "America/New_York", weekly: { 1: [{ from: "09:00", to: "17:00" }] } }) // "2024-06-17T21:00:00Z" — Monday 10:00 to 17:00 local
- * @example nextCloseAt("2024-06-15T16:00:00Z", { timeZone: "America/New_York", weekly: { 1: [{ from: "09:00", to: "17:00" }] } }) // "2024-06-15T16:00:00Z" — already closed
+ * @example nextCloseAt("2024-06-17T08:00:00Z", { timeZone: "Africa/Johannesburg", weekly: { 1: [{ from: "09:00", to: "17:00" }] } }) // "2024-06-17T15:00:00Z" — Monday 10:00 to 17:00 local
+ * @example nextCloseAt("2024-06-15T16:00:00Z", { timeZone: "Africa/Johannesburg", weekly: { 1: [{ from: "09:00", to: "17:00" }] } }) // "2024-06-15T16:00:00Z" — already closed
  * @example nextCloseAt("2024-06-14T23:30:00Z", { timeZone: "UTC", weekly: { 5: [{ from: "23:00", to: "06:00" }] } }) // "2024-06-15T06:00:00Z" — Friday's night window
  * @example nextCloseAt("2024-06-17T14:00:00Z", { timeZone: "UTC", weekly: { 1: [{ from: "00:00", to: "00:00" }], 2: [{ from: "00:00", to: "00:00" }] } }) // "2024-06-19T00:00:00Z" — two touching days are one interval
  * @example nextCloseAt("2024-06-17T14:00:00Z", { timeZone: "UTC", weekly: { 1: [{ from: "09:00", to: "17:00" }] } }, { within: "PT1H" }) // "" — still open an hour later

package/dist/calendar/hours/nextCloseAt.js

@@ -27,8 +27,8 @@ import { firstClosedInstant, instantText, parseOperatingSchedule, parseScheduleD
  * @param optionsArg How far the search goes, and how a window edge on a clock change is resolved
  * @returns UTC instant string ending in "Z", or "" when none within the horizon or on invalid input
  *
- * @example nextCloseAt("2024-06-17T14:00:00Z", { timeZone: "America/New_York", weekly: { 1: [{ from: "09:00", to: "17:00" }] } }) // "2024-06-17T21:00:00Z" — Monday 10:00 to 17:00 local
- * @example nextCloseAt("2024-06-15T16:00:00Z", { timeZone: "America/New_York", weekly: { 1: [{ from: "09:00", to: "17:00" }] } }) // "2024-06-15T16:00:00Z" — already closed
+ * @example nextCloseAt("2024-06-17T08:00:00Z", { timeZone: "Africa/Johannesburg", weekly: { 1: [{ from: "09:00", to: "17:00" }] } }) // "2024-06-17T15:00:00Z" — Monday 10:00 to 17:00 local
+ * @example nextCloseAt("2024-06-15T16:00:00Z", { timeZone: "Africa/Johannesburg", weekly: { 1: [{ from: "09:00", to: "17:00" }] } }) // "2024-06-15T16:00:00Z" — already closed
  * @example nextCloseAt("2024-06-14T23:30:00Z", { timeZone: "UTC", weekly: { 5: [{ from: "23:00", to: "06:00" }] } }) // "2024-06-15T06:00:00Z" — Friday's night window
  * @example nextCloseAt("2024-06-17T14:00:00Z", { timeZone: "UTC", weekly: { 1: [{ from: "00:00", to: "00:00" }], 2: [{ from: "00:00", to: "00:00" }] } }) // "2024-06-19T00:00:00Z" — two touching days are one interval
  * @example nextCloseAt("2024-06-17T14:00:00Z", { timeZone: "UTC", weekly: { 1: [{ from: "09:00", to: "17:00" }] } }, { within: "PT1H" }) // "" — still open an hour later