@northguild/gmt 1.18.0 → 1.20.0

package/dist/calendar/hours/isOpenAt.js

@@ -14,17 +14,23 @@ import { firstOpenInstant, parseOperatingSchedule, parseScheduleDisambiguation,
  * - Returns `false` on invalid input: an invalid instant or `OperatingSchedule`, or a
  *   `disambiguation` that is not one of the four values. Check the schedule with
  *   `operatingIntervals` when "closed" and "invalid" must be told apart.
+ * - **Limit at an offset with seconds.** The instant is placed in the offset's whole-minute zone,
+ *   moved by its seconds, and the moved instant must be inside Temporal's range. So within the
+ *   offset's seconds (under a minute) of the first instant Temporal supports
+ *   (`-271821-04-20T00:00:00Z`), for an offset west of UTC, this returns `false`. There `false` is
+ *   the sentinel, not a reading of the schedule. An offset to the minute has no such limit.
  *
  * @param isoString ISO 8601 instant string to test
  * @param schedule `{ timeZone, weekly, holidays?, overrides? }` operating schedule
  * @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)
  */
 export function isOpenAt(isoString, schedule, optionsArg) {
     try {

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

@@ -14,14 +14,20 @@ import type { Disambiguation, OperatingSchedule } from "../../types/index.js";
  * - Returns `""` on invalid input: an invalid instant or `OperatingSchedule`, a `within` that is
  *   not a non-negative ISO duration, a `disambiguation` that is not one of the four values, and
  *   a search that would go more than 10,000 local dates past the input's date.
+ * - **Limit at an offset with seconds.** The instant is placed in the offset's whole-minute zone,
+ *   moved by its seconds, and the moved instant must be inside Temporal's range. So within the
+ *   offset's seconds (under a minute) of the last instant Temporal supports
+ *   (`+275760-09-13T00:00:00Z`) for an offset east of UTC, or of the first
+ *   (`-271821-04-20T00:00:00Z`) for one west, this returns `""`. An offset to the minute has no
+ *   such limit.
  *
  * @param isoString ISO 8601 instant string to search from, inclusive
  * @param schedule `{ timeZone, weekly, holidays?, overrides? }` operating schedule
  * @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

@@ -15,14 +15,20 @@ import { firstClosedInstant, instantText, parseOperatingSchedule, parseScheduleD
  * - Returns `""` on invalid input: an invalid instant or `OperatingSchedule`, a `within` that is
  *   not a non-negative ISO duration, a `disambiguation` that is not one of the four values, and
  *   a search that would go more than 10,000 local dates past the input's date.
+ * - **Limit at an offset with seconds.** The instant is placed in the offset's whole-minute zone,
+ *   moved by its seconds, and the moved instant must be inside Temporal's range. So within the
+ *   offset's seconds (under a minute) of the last instant Temporal supports
+ *   (`+275760-09-13T00:00:00Z`) for an offset east of UTC, or of the first
+ *   (`-271821-04-20T00:00:00Z`) for one west, this returns `""`. An offset to the minute has no
+ *   such limit.
  *
  * @param isoString ISO 8601 instant string to search from, inclusive
  * @param schedule `{ timeZone, weekly, holidays?, overrides? }` operating schedule
  * @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
@@ -36,7 +42,7 @@ export function nextCloseAt(isoString, schedule, optionsArg) {
         if (disambiguation === null || resolved === null || from === null) {
             return "";
         }
-        const horizon = parseSearchHorizon(from, optionsArg?.within, resolved.timeZone);
+        const horizon = parseSearchHorizon(from, optionsArg?.within, resolved.frame);
         if (horizon === null) {
             return "";
         }

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

@@ -11,15 +11,21 @@ import type { Disambiguation, OperatingSchedule } from "../../types/index.js";
  * - Returns `""` on invalid input: an invalid instant or `OperatingSchedule`, a `within` that is
  *   not a non-negative ISO duration, a `disambiguation` that is not one of the four values, and
  *   a search that would go more than 10,000 local dates past the input's date.
+ * - **Limit at an offset with seconds.** The instant is placed in the offset's whole-minute zone,
+ *   moved by its seconds, and the moved instant must be inside Temporal's range. So within the
+ *   offset's seconds (under a minute) of the last instant Temporal supports
+ *   (`+275760-09-13T00:00:00Z`) for an offset east of UTC, or of the first
+ *   (`-271821-04-20T00:00:00Z`) for one west, this returns `""`. An offset to the minute has no
+ *   such limit.
  *
  * @param isoString ISO 8601 instant string to search from, inclusive
  * @param schedule `{ timeZone, weekly, holidays?, overrides? }` operating schedule
  * @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 nextOpenAt("2024-06-15T16:00:00Z", { timeZone: "America/New_York", weekly: { 1: [{ from: "09:00", to: "17:00" }], 5: [{ from: "09:00", to: "17:00" }] } }) // "2024-06-17T13:00:00Z" — Saturday noon to Monday 09:00 local
- * @example nextOpenAt("2024-06-17T14:00:00Z", { timeZone: "America/New_York", weekly: { 1: [{ from: "09:00", to: "17:00" }] } }) // "2024-06-17T14:00:00Z" — already open
- * @example nextOpenAt("2024-06-15T16:00:00Z", { timeZone: "America/New_York", weekly: { 1: [{ from: "09:00", to: "17:00" }] } }, { within: "P1D" }) // "" — Monday is past the horizon
+ * @example nextOpenAt("2024-06-15T15:00:00Z", { timeZone: "America/Sao_Paulo", weekly: { 1: [{ from: "09:00", to: "17:00" }], 5: [{ from: "09:00", to: "17:00" }] } }) // "2024-06-17T12:00:00Z" — Saturday noon to Monday 09:00 local
+ * @example nextOpenAt("2024-06-17T13:00:00Z", { timeZone: "America/Sao_Paulo", weekly: { 1: [{ from: "09:00", to: "17:00" }] } }) // "2024-06-17T13:00:00Z" — already open
+ * @example nextOpenAt("2024-06-15T15:00:00Z", { timeZone: "America/Sao_Paulo", weekly: { 1: [{ from: "09:00", to: "17:00" }] } }, { within: "P1D" }) // "" — Monday is past the horizon
  * @example nextOpenAt("2024-06-15T16:00:00Z", { timeZone: "UTC", weekly: {} }) // "" — never opens
  * @example nextOpenAt("2024-06-15T16:00:00Z", { timeZone: "UTC", weekly: { 1: [{ from: "09:00", to: "17:00" }] } }, { within: "-P1D" }) // ""
  */

package/dist/calendar/hours/nextOpenAt.js

@@ -12,15 +12,21 @@ import { firstOpenInstant, instantText, parseOperatingSchedule, parseScheduleDis
  * - Returns `""` on invalid input: an invalid instant or `OperatingSchedule`, a `within` that is
  *   not a non-negative ISO duration, a `disambiguation` that is not one of the four values, and
  *   a search that would go more than 10,000 local dates past the input's date.
+ * - **Limit at an offset with seconds.** The instant is placed in the offset's whole-minute zone,
+ *   moved by its seconds, and the moved instant must be inside Temporal's range. So within the
+ *   offset's seconds (under a minute) of the last instant Temporal supports
+ *   (`+275760-09-13T00:00:00Z`) for an offset east of UTC, or of the first
+ *   (`-271821-04-20T00:00:00Z`) for one west, this returns `""`. An offset to the minute has no
+ *   such limit.
  *
  * @param isoString ISO 8601 instant string to search from, inclusive
  * @param schedule `{ timeZone, weekly, holidays?, overrides? }` operating schedule
  * @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 nextOpenAt("2024-06-15T16:00:00Z", { timeZone: "America/New_York", weekly: { 1: [{ from: "09:00", to: "17:00" }], 5: [{ from: "09:00", to: "17:00" }] } }) // "2024-06-17T13:00:00Z" — Saturday noon to Monday 09:00 local
- * @example nextOpenAt("2024-06-17T14:00:00Z", { timeZone: "America/New_York", weekly: { 1: [{ from: "09:00", to: "17:00" }] } }) // "2024-06-17T14:00:00Z" — already open
- * @example nextOpenAt("2024-06-15T16:00:00Z", { timeZone: "America/New_York", weekly: { 1: [{ from: "09:00", to: "17:00" }] } }, { within: "P1D" }) // "" — Monday is past the horizon
+ * @example nextOpenAt("2024-06-15T15:00:00Z", { timeZone: "America/Sao_Paulo", weekly: { 1: [{ from: "09:00", to: "17:00" }], 5: [{ from: "09:00", to: "17:00" }] } }) // "2024-06-17T12:00:00Z" — Saturday noon to Monday 09:00 local
+ * @example nextOpenAt("2024-06-17T13:00:00Z", { timeZone: "America/Sao_Paulo", weekly: { 1: [{ from: "09:00", to: "17:00" }] } }) // "2024-06-17T13:00:00Z" — already open
+ * @example nextOpenAt("2024-06-15T15:00:00Z", { timeZone: "America/Sao_Paulo", weekly: { 1: [{ from: "09:00", to: "17:00" }] } }, { within: "P1D" }) // "" — Monday is past the horizon
  * @example nextOpenAt("2024-06-15T16:00:00Z", { timeZone: "UTC", weekly: {} }) // "" — never opens
  * @example nextOpenAt("2024-06-15T16:00:00Z", { timeZone: "UTC", weekly: { 1: [{ from: "09:00", to: "17:00" }] } }, { within: "-P1D" }) // ""
  */
@@ -32,7 +38,7 @@ export function nextOpenAt(isoString, schedule, optionsArg) {
         if (disambiguation === null || resolved === null || from === null) {
             return "";
         }
-        const horizon = parseSearchHorizon(from, optionsArg?.within, resolved.timeZone);
+        const horizon = parseSearchHorizon(from, optionsArg?.within, resolved.frame);
         if (horizon === null) {
             return "";
         }

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

@@ -18,14 +18,19 @@ import type { Disambiguation, Interval, OperatingSchedule } from "../../types/in
  *   for one date), when `range` is not a valid `Interval`, when `disambiguation` is not one of
  *   the four values, and when the range spans more than 10,000 local dates (about 27 years)
  *   counted from the date `range.start` falls on.
+ * - **Limit at an offset with seconds.** The instant is placed in the offset's whole-minute zone,
+ *   moved by its seconds, and the moved instant must be inside Temporal's range. So within the
+ *   offset's seconds (under a minute) of the first instant Temporal supports
+ *   (`-271821-04-20T00:00:00Z`), for an offset west of UTC, this returns `[]`. An offset to the
+ *   minute has no such limit.
  *
  * @param schedule `{ timeZone, weekly, holidays?, overrides? }` operating schedule
  * @param range `{ start, end }` record of ISO 8601 instant strings to expand the schedule inside
  * @param optionsArg How a window edge on a clock change is resolved
  * @returns sorted, merged `{ start, end }` records of the open instants, or [] on invalid input
  *
- * @example operatingIntervals({ timeZone: "America/New_York", weekly: { 4: [{ from: "09:00", to: "17:00" }], 5: [{ from: "09:00", to: "17:00" }] }, holidays: ["2024-07-04"] }, { start: "2024-07-04T00:00:00Z", end: "2024-07-06T00:00:00Z" }) // [{ start: "2024-07-05T13:00:00Z", end: "2024-07-05T21:00:00Z" }] — the holiday is closed
- * @example operatingIntervals({ timeZone: "America/New_York", weekly: { 4: [{ from: "09:00", to: "17:00" }] }, holidays: ["2024-07-04"], overrides: [{ date: "2024-07-04", windows: [{ from: "10:00", to: "12:00" }] }] }, { start: "2024-07-04T00:00:00Z", end: "2024-07-05T00:00:00Z" }) // [{ start: "2024-07-04T14:00:00Z", end: "2024-07-04T16:00:00Z" }] — the override wins
+ * @example operatingIntervals({ timeZone: "Africa/Kigali", weekly: { 4: [{ from: "09:00", to: "17:00" }], 5: [{ from: "09:00", to: "17:00" }] }, holidays: ["2024-07-04"] }, { start: "2024-07-04T00:00:00Z", end: "2024-07-06T00:00:00Z" }) // [{ start: "2024-07-05T07:00:00Z", end: "2024-07-05T15:00:00Z" }] — the holiday is closed
+ * @example operatingIntervals({ timeZone: "Africa/Kigali", weekly: { 4: [{ from: "09:00", to: "17:00" }] }, holidays: ["2024-07-04"], overrides: [{ date: "2024-07-04", windows: [{ from: "10:00", to: "12:00" }] }] }, { start: "2024-07-04T00:00:00Z", end: "2024-07-05T00:00:00Z" }) // [{ start: "2024-07-04T08:00:00Z", end: "2024-07-04T10:00:00Z" }] — the override wins
  * @example operatingIntervals({ timeZone: "UTC", weekly: { 1: [{ from: "09:00", to: "17:00" }] } }, { start: "2024-06-10T12:00:00Z", end: "2024-06-10T14:00:00Z" }) // [{ start: "2024-06-10T12:00:00Z", end: "2024-06-10T14:00:00Z" }] — clipped to the range
  * @example operatingIntervals({ timeZone: "UTC", weekly: { 1: [{ from: "09:00", to: "17:00" }] }, overrides: [{ date: "2024-06-10", windows: [] }] }, { start: "2024-06-10T00:00:00Z", end: "2024-06-11T00:00:00Z" }) // [] — closed by override
  * @example operatingIntervals({ timeZone: "Invalid/Zone", weekly: {} }, { start: "2024-06-10T00:00:00Z", end: "2024-06-11T00:00:00Z" }) // []

package/dist/calendar/hours/operatingIntervals.js

@@ -1,5 +1,5 @@
 import { parseIntervalNanoseconds } from "../../internal/index.js";
-import { parseOperatingSchedule, parseScheduleDisambiguation, scheduleRunsWithin, } from "../../internal/operatingSchedule.js";
+import { parseOperatingSchedule, parseScheduleDisambiguation, runText, scheduleRunsWithin, } from "../../internal/operatingSchedule.js";
 /**
  * Return the instants an `OperatingSchedule` is open inside `range`: its weekly windows with
  * holidays closed and overrides applied, resolved in the schedule's zone.
@@ -19,14 +19,19 @@ import { parseOperatingSchedule, parseScheduleDisambiguation, scheduleRunsWithin
  *   for one date), when `range` is not a valid `Interval`, when `disambiguation` is not one of
  *   the four values, and when the range spans more than 10,000 local dates (about 27 years)
  *   counted from the date `range.start` falls on.
+ * - **Limit at an offset with seconds.** The instant is placed in the offset's whole-minute zone,
+ *   moved by its seconds, and the moved instant must be inside Temporal's range. So within the
+ *   offset's seconds (under a minute) of the first instant Temporal supports
+ *   (`-271821-04-20T00:00:00Z`), for an offset west of UTC, this returns `[]`. An offset to the
+ *   minute has no such limit.
  *
  * @param schedule `{ timeZone, weekly, holidays?, overrides? }` operating schedule
  * @param range `{ start, end }` record of ISO 8601 instant strings to expand the schedule inside
  * @param optionsArg How a window edge on a clock change is resolved
  * @returns sorted, merged `{ start, end }` records of the open instants, or [] on invalid input
  *
- * @example operatingIntervals({ timeZone: "America/New_York", weekly: { 4: [{ from: "09:00", to: "17:00" }], 5: [{ from: "09:00", to: "17:00" }] }, holidays: ["2024-07-04"] }, { start: "2024-07-04T00:00:00Z", end: "2024-07-06T00:00:00Z" }) // [{ start: "2024-07-05T13:00:00Z", end: "2024-07-05T21:00:00Z" }] — the holiday is closed
- * @example operatingIntervals({ timeZone: "America/New_York", weekly: { 4: [{ from: "09:00", to: "17:00" }] }, holidays: ["2024-07-04"], overrides: [{ date: "2024-07-04", windows: [{ from: "10:00", to: "12:00" }] }] }, { start: "2024-07-04T00:00:00Z", end: "2024-07-05T00:00:00Z" }) // [{ start: "2024-07-04T14:00:00Z", end: "2024-07-04T16:00:00Z" }] — the override wins
+ * @example operatingIntervals({ timeZone: "Africa/Kigali", weekly: { 4: [{ from: "09:00", to: "17:00" }], 5: [{ from: "09:00", to: "17:00" }] }, holidays: ["2024-07-04"] }, { start: "2024-07-04T00:00:00Z", end: "2024-07-06T00:00:00Z" }) // [{ start: "2024-07-05T07:00:00Z", end: "2024-07-05T15:00:00Z" }] — the holiday is closed
+ * @example operatingIntervals({ timeZone: "Africa/Kigali", weekly: { 4: [{ from: "09:00", to: "17:00" }] }, holidays: ["2024-07-04"], overrides: [{ date: "2024-07-04", windows: [{ from: "10:00", to: "12:00" }] }] }, { start: "2024-07-04T00:00:00Z", end: "2024-07-05T00:00:00Z" }) // [{ start: "2024-07-04T08:00:00Z", end: "2024-07-04T10:00:00Z" }] — the override wins
  * @example operatingIntervals({ timeZone: "UTC", weekly: { 1: [{ from: "09:00", to: "17:00" }] } }, { start: "2024-06-10T12:00:00Z", end: "2024-06-10T14:00:00Z" }) // [{ start: "2024-06-10T12:00:00Z", end: "2024-06-10T14:00:00Z" }] — clipped to the range
  * @example operatingIntervals({ timeZone: "UTC", weekly: { 1: [{ from: "09:00", to: "17:00" }] }, overrides: [{ date: "2024-06-10", windows: [] }] }, { start: "2024-06-10T00:00:00Z", end: "2024-06-11T00:00:00Z" }) // [] — closed by override
  * @example operatingIntervals({ timeZone: "Invalid/Zone", weekly: {} }, { start: "2024-06-10T00:00:00Z", end: "2024-06-11T00:00:00Z" }) // []
@@ -40,9 +45,7 @@ export function operatingIntervals(schedule, range, optionsArg) {
             return [];
         }
         const runs = scheduleRunsWithin(resolved, bounds, disambiguation);
-        return runs === null
-            ? []
-            : runs.map((run) => ({ start: run.startText, end: run.endText }));
+        return runs === null ? [] : runs.map(runText);
     }
     catch {
         // Never throws (Core Rule 3): a hostile

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

@@ -8,12 +8,17 @@ import type { Disambiguation, OperatingSchedule } from "../../types/index.js";
  *   waited `PT2H` of open time.
  * - Hours are the largest unit (`PT40H`, not `P1DT16H`): an open-time total has no calendar.
  *   Exact to the nanosecond, and elapsed time, not wall-clock distance, so a 00:00–00:00 window
- *   on a New York fall-back date adds 25 hours.
+ *   on a London fall-back date adds 25 hours.
  * - Holidays and overrides apply as in `operatingIntervals`.
  * - `start === end` returns `"PT0S"`.
  * - Returns `""` on invalid input: an invalid instant or `OperatingSchedule`, `start` after
  *   `end`, a `disambiguation` that is not one of the four values, and a range spanning more than
  *   10,000 local dates (about 27 years) counted from the date `start` falls on.
+ * - **Limit at an offset with seconds.** The instant is placed in the offset's whole-minute zone,
+ *   moved by its seconds, and the moved instant must be inside Temporal's range. So within the
+ *   offset's seconds (under a minute) of the first instant Temporal supports
+ *   (`-271821-04-20T00:00:00Z`), for an offset west of UTC, this returns `""`. An offset to the
+ *   minute has no such limit.
  *
  * @param start ISO 8601 instant string where the clock starts (inclusive)
  * @param end ISO 8601 instant string where the clock stops (exclusive)
@@ -21,9 +26,9 @@ import type { Disambiguation, OperatingSchedule } from "../../types/index.js";
  * @param optionsArg How a window edge on a clock change is resolved
  * @returns ISO 8601 duration string of the open time, or "" on invalid input
  *
- * @example operatingTimeBetween("2024-06-14T20:00:00Z", "2024-06-17T14:00:00Z", { timeZone: "America/New_York", weekly: { 1: [{ from: "09:00", to: "17:00" }], 5: [{ from: "09:00", to: "17:00" }] } }) // "PT2H" — Friday 16:00 to Monday 10:00 local
+ * @example operatingTimeBetween("2024-06-14T10:30:00Z", "2024-06-17T04:30:00Z", { timeZone: "Asia/Kolkata", weekly: { 1: [{ from: "09:00", to: "17:00" }], 5: [{ from: "09:00", to: "17:00" }] } }) // "PT2H" — Friday 16:00 to Monday 10:00 local
  * @example operatingTimeBetween("2024-06-15T00:00:00Z", "2024-06-16T00:00:00Z", { timeZone: "UTC", weekly: { 1: [{ from: "09:00", to: "17:00" }] } }) // "PT0S" — a closed Saturday
- * @example operatingTimeBetween("2024-11-03T04:00:00Z", "2024-11-04T05:00:00Z", { timeZone: "America/New_York", weekly: { 7: [{ from: "00:00", to: "00:00" }] } }) // "PT25H" — the fall-back day
+ * @example operatingTimeBetween("2024-10-26T23:00:00Z", "2024-10-28T00:00:00Z", { timeZone: "Europe/London", weekly: { 7: [{ from: "00:00", to: "00:00" }] } }) // "PT25H" — the fall-back day
  * @example operatingTimeBetween("2024-06-10T09:00:00Z", "2024-06-10T09:30:00.5Z", { timeZone: "UTC", weekly: { 1: [{ from: "09:00", to: "17:00" }] } }) // "PT30M0.5S"
  * @example operatingTimeBetween("2024-06-17T00:00:00Z", "2024-06-10T00:00:00Z", { timeZone: "UTC", weekly: {} }) // "" — start after end
  */

package/dist/calendar/hours/operatingTimeBetween.js

@@ -1,5 +1,5 @@
 import { formatHourDuration, parseIntervalNanoseconds } from "../../internal/index.js";
-import { parseOperatingSchedule, parseScheduleDisambiguation, scheduleRunsWithin, } from "../../internal/operatingSchedule.js";
+import { parseOperatingSchedule, parseScheduleDisambiguation, openTimeWithin, } from "../../internal/operatingSchedule.js";
 /**
  * Return how much open time `schedule` has between two instants, as an exact ISO duration.
  *
@@ -9,12 +9,17 @@ import { parseOperatingSchedule, parseScheduleDisambiguation, scheduleRunsWithin
  *   waited `PT2H` of open time.
  * - Hours are the largest unit (`PT40H`, not `P1DT16H`): an open-time total has no calendar.
  *   Exact to the nanosecond, and elapsed time, not wall-clock distance, so a 00:00–00:00 window
- *   on a New York fall-back date adds 25 hours.
+ *   on a London fall-back date adds 25 hours.
  * - Holidays and overrides apply as in `operatingIntervals`.
  * - `start === end` returns `"PT0S"`.
  * - Returns `""` on invalid input: an invalid instant or `OperatingSchedule`, `start` after
  *   `end`, a `disambiguation` that is not one of the four values, and a range spanning more than
  *   10,000 local dates (about 27 years) counted from the date `start` falls on.
+ * - **Limit at an offset with seconds.** The instant is placed in the offset's whole-minute zone,
+ *   moved by its seconds, and the moved instant must be inside Temporal's range. So within the
+ *   offset's seconds (under a minute) of the first instant Temporal supports
+ *   (`-271821-04-20T00:00:00Z`), for an offset west of UTC, this returns `""`. An offset to the
+ *   minute has no such limit.
  *
  * @param start ISO 8601 instant string where the clock starts (inclusive)
  * @param end ISO 8601 instant string where the clock stops (exclusive)
@@ -22,9 +27,9 @@ import { parseOperatingSchedule, parseScheduleDisambiguation, scheduleRunsWithin
  * @param optionsArg How a window edge on a clock change is resolved
  * @returns ISO 8601 duration string of the open time, or "" on invalid input
  *
- * @example operatingTimeBetween("2024-06-14T20:00:00Z", "2024-06-17T14:00:00Z", { timeZone: "America/New_York", weekly: { 1: [{ from: "09:00", to: "17:00" }], 5: [{ from: "09:00", to: "17:00" }] } }) // "PT2H" — Friday 16:00 to Monday 10:00 local
+ * @example operatingTimeBetween("2024-06-14T10:30:00Z", "2024-06-17T04:30:00Z", { timeZone: "Asia/Kolkata", weekly: { 1: [{ from: "09:00", to: "17:00" }], 5: [{ from: "09:00", to: "17:00" }] } }) // "PT2H" — Friday 16:00 to Monday 10:00 local
  * @example operatingTimeBetween("2024-06-15T00:00:00Z", "2024-06-16T00:00:00Z", { timeZone: "UTC", weekly: { 1: [{ from: "09:00", to: "17:00" }] } }) // "PT0S" — a closed Saturday
- * @example operatingTimeBetween("2024-11-03T04:00:00Z", "2024-11-04T05:00:00Z", { timeZone: "America/New_York", weekly: { 7: [{ from: "00:00", to: "00:00" }] } }) // "PT25H" — the fall-back day
+ * @example operatingTimeBetween("2024-10-26T23:00:00Z", "2024-10-28T00:00:00Z", { timeZone: "Europe/London", weekly: { 7: [{ from: "00:00", to: "00:00" }] } }) // "PT25H" — the fall-back day
  * @example operatingTimeBetween("2024-06-10T09:00:00Z", "2024-06-10T09:30:00.5Z", { timeZone: "UTC", weekly: { 1: [{ from: "09:00", to: "17:00" }] } }) // "PT30M0.5S"
  * @example operatingTimeBetween("2024-06-17T00:00:00Z", "2024-06-10T00:00:00Z", { timeZone: "UTC", weekly: {} }) // "" — start after end
  */
@@ -36,10 +41,8 @@ export function operatingTimeBetween(start, end, schedule, optionsArg) {
         if (disambiguation === null || resolved === null || range === null) {
             return "";
         }
-        const runs = scheduleRunsWithin(resolved, range, disambiguation);
-        return runs === null
-            ? ""
-            : formatHourDuration(runs.reduce((total, run) => total + (run.end - run.start), 0n));
+        const open = openTimeWithin(resolved, range, disambiguation);
+        return open === null ? "" : formatHourDuration(open);
     }
     catch {
         // Never throws (Core Rule 3): a hostile

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

@@ -17,7 +17,7 @@ import type { Disambiguation, Interval, OperatingSchedule } from "../../types/in
  *   read `"earlier"`, its `to` read `"later"`) overlaps `range`. A rejected window elsewhere
  *   does not matter.
  * - Windows are elapsed time between their resolved edges, so the wall-clock length is not the
- *   real one on transition nights: in New York, 23:00–06:00 is 8 hours across the fall-back
+ *   real one on transition nights: in London, 23:00–06:00 is 8 hours across the fall-back
  *   night and 6 across the spring-forward one, and 00:00–00:00 is 25 and 23 hours.
  * - A window whose edges resolve to an empty or inverted span on a transition night — only a
  *   window shorter than the gap it straddles — is empty that day and left out.
@@ -31,22 +31,29 @@ import type { Disambiguation, Interval, OperatingSchedule } from "../../types/in
  *   `range` is not a valid `Interval`, when `timeZone` is invalid, when `disambiguation` is not
  *   one of the four values, and when the range spans more than 10,000 local dates (about 27
  *   years) counted from the date `range.start` falls on, rather than a truncated list.
+ * - **Limit at an offset with seconds.** The instant is placed in the offset's whole-minute zone,
+ *   moved by its seconds, and the moved instant must be inside Temporal's range. So within the
+ *   offset's seconds (under a minute) of the first instant Temporal supports
+ *   (`-271821-04-20T00:00:00Z`), for an offset west of UTC, this returns `[]`. An offset to the
+ *   minute has no such limit.
  *
  * @param weekly windows by ISO weekday, `{ 1: [{ from: "09:00", to: "17:00" }], … }`
  * @param range `{ start, end }` record of ISO 8601 instant strings to expand the pattern inside
- * @param timeZone IANA name or UTC offset the windows are read in
+ * @param timeZone IANA name or UTC offset the windows are read in: a time zone identifier
+ *   (`+05:30`, `+0530`, `-08`) or a stored offset (`±HH:MM[:SS]`, what `getTimeZoneOffset` returns)
  * @param optionsArg How a window edge on a clock change is resolved
  * @returns sorted, merged `{ start, end }` records of the open instants, or [] on invalid input
  *
- * @example recurringWindows({ 1: [{ from: "09:00", to: "17:00" }] }, { start: "2024-06-10T00:00:00Z", end: "2024-06-11T00:00:00Z" }, "America/New_York") // [{ start: "2024-06-10T13:00:00Z", end: "2024-06-10T21:00:00Z" }]
+ * @example recurringWindows({ 1: [{ from: "09:00", to: "17:00" }] }, { start: "2024-06-10T00:00:00Z", end: "2024-06-11T00:00:00Z" }, "Africa/Johannesburg") // [{ start: "2024-06-10T07:00:00Z", end: "2024-06-10T15:00:00Z" }]
  * @example recurringWindows({ 5: [{ from: "23:00", to: "06:00" }] }, { start: "2024-06-14T00:00:00Z", end: "2024-06-16T00:00:00Z" }, "UTC") // [{ start: "2024-06-14T23:00:00Z", end: "2024-06-15T06:00:00Z" }] — Friday night into Saturday
- * @example recurringWindows({ 6: [{ from: "23:00", to: "06:00" }] }, { start: "2024-11-02T00:00:00Z", end: "2024-11-04T00:00:00Z" }, "America/New_York") // [{ start: "2024-11-03T03:00:00Z", end: "2024-11-03T11:00:00Z" }] — 8 hours across the fall-back night
- * @example recurringWindows({ 7: [{ from: "02:30", to: "04:00" }] }, { start: "2024-03-10T00:00:00Z", end: "2024-03-11T00:00:00Z" }, "America/New_York") // [{ start: "2024-03-10T07:30:00Z", end: "2024-03-10T08:00:00Z" }] — 02:30 does not exist; "compatible" reads it as 03:30
- * @example recurringWindows({ 7: [{ from: "02:30", to: "04:00" }] }, { start: "2024-03-10T00:00:00Z", end: "2024-03-11T00:00:00Z" }, "America/New_York", { disambiguation: "reject" }) // []
+ * @example recurringWindows({ 6: [{ from: "23:00", to: "06:00" }] }, { start: "2024-10-26T00:00:00Z", end: "2024-10-28T00:00:00Z" }, "Europe/London") // [{ start: "2024-10-26T22:00:00Z", end: "2024-10-27T06:00:00Z" }] — 8 hours across the fall-back night
+ * @example recurringWindows({ 7: [{ from: "02:30", to: "04:00" }] }, { start: "2024-10-05T12:00:00Z", end: "2024-10-06T12:00:00Z" }, "Australia/Sydney") // [{ start: "2024-10-05T16:30:00Z", end: "2024-10-05T17:00:00Z" }] — 02:30 does not exist; "compatible" reads it as 03:30
+ * @example recurringWindows({ 7: [{ from: "02:30", to: "04:00" }] }, { start: "2024-10-05T12:00:00Z", end: "2024-10-06T12:00:00Z" }, "Australia/Sydney", { disambiguation: "reject" }) // []
  * @example recurringWindows({ 1: [{ from: "00:00", to: "00:00" }], 2: [{ from: "00:00", to: "00:00" }] }, { start: "2024-06-10T00:00:00Z", end: "2024-06-13T00:00:00Z" }, "UTC") // [{ start: "2024-06-10T00:00:00Z", end: "2024-06-12T00:00:00Z" }] — touching days merge
  * @example recurringWindows({ 8: [{ from: "09:00", to: "17:00" }] }, { start: "2024-06-10T00:00:00Z", end: "2024-06-11T00:00:00Z" }, "UTC") // [] — not an ISO weekday
  * @example recurringWindows({ 1: [{ from: "9am", to: "17:00" }] }, { start: "2024-06-10T00:00:00Z", end: "2024-06-11T00:00:00Z" }, "UTC") // [] — malformed window
  * @example recurringWindows({ 1: [{ from: "09:00", to: "17:00" }] }, { start: "2024-06-10T00:00:00Z", end: "2024-06-11T00:00:00Z" }, "Invalid/Zone") // []
+ * @example recurringWindows({ 4: [{ from: "08:00", to: "17:00" }] }, { start: "1970-01-01T00:00:00Z", end: "1970-01-02T00:00:00Z" }, "-00:44:30") // [{ start: "1970-01-01T08:44:30Z", end: "1970-01-01T17:44:30Z" }]
  */
 export declare function recurringWindows(weekly: OperatingSchedule["weekly"], range: Interval, timeZone: string, optionsArg?: {
     /**

package/dist/calendar/hours/recurringWindows.js

@@ -1,6 +1,5 @@
-import { parseIntervalNanoseconds } from "../../internal/index.js";
-import { parseScheduleDisambiguation, parseWeeklyPattern, scheduleRunsWithin, } from "../../internal/operatingSchedule.js";
-import { isValidTimeZone } from "../../zoned/validate/index.js";
+import { parseIntervalNanoseconds, zoneFrame } from "../../internal/index.js";
+import { parseScheduleDisambiguation, parseWeeklyPattern, runText, scheduleRunsWithin, } from "../../internal/operatingSchedule.js";
 /**
  * Return the instants a weekly pattern of local windows is open inside `range`, read in
  * `timeZone`: the primitive under operating hours, curfews and recurring crew windows.
@@ -19,7 +18,7 @@ import { isValidTimeZone } from "../../zoned/validate/index.js";
  *   read `"earlier"`, its `to` read `"later"`) overlaps `range`. A rejected window elsewhere
  *   does not matter.
  * - Windows are elapsed time between their resolved edges, so the wall-clock length is not the
- *   real one on transition nights: in New York, 23:00–06:00 is 8 hours across the fall-back
+ *   real one on transition nights: in London, 23:00–06:00 is 8 hours across the fall-back
  *   night and 6 across the spring-forward one, and 00:00–00:00 is 25 and 23 hours.
  * - A window whose edges resolve to an empty or inverted span on a transition night — only a
  *   window shorter than the gap it straddles — is empty that day and left out.
@@ -33,44 +32,52 @@ import { isValidTimeZone } from "../../zoned/validate/index.js";
  *   `range` is not a valid `Interval`, when `timeZone` is invalid, when `disambiguation` is not
  *   one of the four values, and when the range spans more than 10,000 local dates (about 27
  *   years) counted from the date `range.start` falls on, rather than a truncated list.
+ * - **Limit at an offset with seconds.** The instant is placed in the offset's whole-minute zone,
+ *   moved by its seconds, and the moved instant must be inside Temporal's range. So within the
+ *   offset's seconds (under a minute) of the first instant Temporal supports
+ *   (`-271821-04-20T00:00:00Z`), for an offset west of UTC, this returns `[]`. An offset to the
+ *   minute has no such limit.
  *
  * @param weekly windows by ISO weekday, `{ 1: [{ from: "09:00", to: "17:00" }], … }`
  * @param range `{ start, end }` record of ISO 8601 instant strings to expand the pattern inside
- * @param timeZone IANA name or UTC offset the windows are read in
+ * @param timeZone IANA name or UTC offset the windows are read in: a time zone identifier
+ *   (`+05:30`, `+0530`, `-08`) or a stored offset (`±HH:MM[:SS]`, what `getTimeZoneOffset` returns)
  * @param optionsArg How a window edge on a clock change is resolved
  * @returns sorted, merged `{ start, end }` records of the open instants, or [] on invalid input
  *
- * @example recurringWindows({ 1: [{ from: "09:00", to: "17:00" }] }, { start: "2024-06-10T00:00:00Z", end: "2024-06-11T00:00:00Z" }, "America/New_York") // [{ start: "2024-06-10T13:00:00Z", end: "2024-06-10T21:00:00Z" }]
+ * @example recurringWindows({ 1: [{ from: "09:00", to: "17:00" }] }, { start: "2024-06-10T00:00:00Z", end: "2024-06-11T00:00:00Z" }, "Africa/Johannesburg") // [{ start: "2024-06-10T07:00:00Z", end: "2024-06-10T15:00:00Z" }]
  * @example recurringWindows({ 5: [{ from: "23:00", to: "06:00" }] }, { start: "2024-06-14T00:00:00Z", end: "2024-06-16T00:00:00Z" }, "UTC") // [{ start: "2024-06-14T23:00:00Z", end: "2024-06-15T06:00:00Z" }] — Friday night into Saturday
- * @example recurringWindows({ 6: [{ from: "23:00", to: "06:00" }] }, { start: "2024-11-02T00:00:00Z", end: "2024-11-04T00:00:00Z" }, "America/New_York") // [{ start: "2024-11-03T03:00:00Z", end: "2024-11-03T11:00:00Z" }] — 8 hours across the fall-back night
- * @example recurringWindows({ 7: [{ from: "02:30", to: "04:00" }] }, { start: "2024-03-10T00:00:00Z", end: "2024-03-11T00:00:00Z" }, "America/New_York") // [{ start: "2024-03-10T07:30:00Z", end: "2024-03-10T08:00:00Z" }] — 02:30 does not exist; "compatible" reads it as 03:30
- * @example recurringWindows({ 7: [{ from: "02:30", to: "04:00" }] }, { start: "2024-03-10T00:00:00Z", end: "2024-03-11T00:00:00Z" }, "America/New_York", { disambiguation: "reject" }) // []
+ * @example recurringWindows({ 6: [{ from: "23:00", to: "06:00" }] }, { start: "2024-10-26T00:00:00Z", end: "2024-10-28T00:00:00Z" }, "Europe/London") // [{ start: "2024-10-26T22:00:00Z", end: "2024-10-27T06:00:00Z" }] — 8 hours across the fall-back night
+ * @example recurringWindows({ 7: [{ from: "02:30", to: "04:00" }] }, { start: "2024-10-05T12:00:00Z", end: "2024-10-06T12:00:00Z" }, "Australia/Sydney") // [{ start: "2024-10-05T16:30:00Z", end: "2024-10-05T17:00:00Z" }] — 02:30 does not exist; "compatible" reads it as 03:30
+ * @example recurringWindows({ 7: [{ from: "02:30", to: "04:00" }] }, { start: "2024-10-05T12:00:00Z", end: "2024-10-06T12:00:00Z" }, "Australia/Sydney", { disambiguation: "reject" }) // []
  * @example recurringWindows({ 1: [{ from: "00:00", to: "00:00" }], 2: [{ from: "00:00", to: "00:00" }] }, { start: "2024-06-10T00:00:00Z", end: "2024-06-13T00:00:00Z" }, "UTC") // [{ start: "2024-06-10T00:00:00Z", end: "2024-06-12T00:00:00Z" }] — touching days merge
  * @example recurringWindows({ 8: [{ from: "09:00", to: "17:00" }] }, { start: "2024-06-10T00:00:00Z", end: "2024-06-11T00:00:00Z" }, "UTC") // [] — not an ISO weekday
  * @example recurringWindows({ 1: [{ from: "9am", to: "17:00" }] }, { start: "2024-06-10T00:00:00Z", end: "2024-06-11T00:00:00Z" }, "UTC") // [] — malformed window
  * @example recurringWindows({ 1: [{ from: "09:00", to: "17:00" }] }, { start: "2024-06-10T00:00:00Z", end: "2024-06-11T00:00:00Z" }, "Invalid/Zone") // []
+ * @example recurringWindows({ 4: [{ from: "08:00", to: "17:00" }] }, { start: "1970-01-01T00:00:00Z", end: "1970-01-02T00:00:00Z" }, "-00:44:30") // [{ start: "1970-01-01T08:44:30Z", end: "1970-01-01T17:44:30Z" }]
  */
 export function recurringWindows(weekly, range, timeZone, optionsArg) {
     try {
         const disambiguation = parseScheduleDisambiguation(optionsArg);
         const weeklyWindows = parseWeeklyPattern(weekly);
         const bounds = parseIntervalNanoseconds(range);
+        const frame = zoneFrame(timeZone);
         if (disambiguation === null ||
             weeklyWindows === null ||
             bounds === null ||
             typeof timeZone !== "string" ||
-            !isValidTimeZone(timeZone)) {
+            frame === null) {
             return [];
         }
         const runs = scheduleRunsWithin({
             timeZone,
+            frame,
             weekly: weeklyWindows,
-            holidays: new Set(),
+            holidays: new Int32Array(0),
             overrides: new Map(),
+            specials: new Int32Array(0),
         }, bounds, disambiguation);
-        return runs === null
-            ? []
-            : runs.map((run) => ({ start: run.startText, end: run.endText }));
+        return runs === null ? [] : runs.map(runText);
     }
     catch {
         // Never throws (Core Rule 3): a hostile

package/dist/calendar/index.d.ts

@@ -1,4 +1,4 @@
-export * from "@js-temporal/polyfill";
+export { Intl, Temporal, toTemporalInstant } from "../internal/temporal.js";
 export * from "./business/index.js";
 export * from "./calculate/index.js";
 export * from "./hours/index.js";

package/dist/calendar/index.js

@@ -1,5 +1,5 @@
-// Re-export the Temporal polyfill (`Temporal`, `Intl`, `toTemporalInstant`) so every namespace subpath offers it
-export * from "@js-temporal/polyfill";
+// Re-export `Temporal`, `Intl` and `toTemporalInstant` from the internal seam so every namespace subpath offers them
+export { Intl, Temporal, toTemporalInstant } from "../internal/temporal.js";
 export * from "./business/index.js";
 export * from "./calculate/index.js";
 export * from "./hours/index.js";

package/dist/calendar/validate/index.d.ts

@@ -1,4 +1,7 @@
 export * from "./isValidBusinessCalendar.js";
+export * from "./isValidFiscalCalendar.js";
+export * from "./isValidFiscalExtraWeek.js";
 export * from "./isValidFiscalPattern.js";
+export * from "./isValidFiscalYearLabel.js";
 export * from "./isValidRollConvention.js";
 export * from "./isValidZoneBucketUnit.js";

package/dist/calendar/validate/index.js

@@ -1,4 +1,7 @@
 export * from "./isValidBusinessCalendar.js";
+export * from "./isValidFiscalCalendar.js";
+export * from "./isValidFiscalExtraWeek.js";
 export * from "./isValidFiscalPattern.js";
+export * from "./isValidFiscalYearLabel.js";
 export * from "./isValidRollConvention.js";
 export * from "./isValidZoneBucketUnit.js";

package/dist/calendar/validate/isValidFiscalCalendar.d.ts

@@ -0,0 +1,23 @@
+import type { FiscalCalendar } from "../../types/index.js";
+/**
+ * Return true when `calendar` is a `FiscalCalendar` that `getFiscalPeriod` accepts.
+ *
+ * - `pattern` must be `"4-5-4"`, `"4-4-5"` or `"5-4-4"`.
+ * - `yearEndsOn` must be a plain ISO date. A datetime or a date that does not exist is not.
+ * - `extraWeek` must be `"firstPeriod"` or `"lastPeriod"`, and `yearLabel` must be
+ *   `"startYear"`, `"endYear"` or `"majorityYear"`. Both are required: there is no default.
+ * - Extra properties are ignored.
+ * - Returns `false` for non-objects, `null` and arrays.
+ * - `getFiscalPeriod` returns null for a calendar this rejects, the same sentinel it returns
+ *   for an invalid date. Check the calendar here to tell the two apart.
+ *
+ * @param calendar candidate value of any type
+ * @returns boolean indicating whether `getFiscalPeriod` accepts it
+ *
+ * @example isValidFiscalCalendar({ pattern: "4-5-4", yearEndsOn: "2026-01-31", extraWeek: "lastPeriod", yearLabel: "startYear" }) // true
+ * @example isValidFiscalCalendar({ pattern: "4-5-4", yearEndsOn: "2026-01-31" }) // false (the 1.19 shape: no extraWeek or yearLabel)
+ * @example isValidFiscalCalendar({ pattern: "4-5-4", yearEndsOn: "2026-02-30", extraWeek: "lastPeriod", yearLabel: "startYear" }) // false
+ * @example isValidFiscalCalendar("4-5-4") // false
+ * @example isValidFiscalCalendar([]) // false
+ */
+export declare function isValidFiscalCalendar(calendar: unknown): calendar is FiscalCalendar;

package/dist/calendar/validate/isValidFiscalCalendar.js

@@ -0,0 +1,44 @@
+import { isObject } from "../../internal/isObject.js";
+import { isValidDate } from "../../plain/validate/index.js";
+import { isValidFiscalExtraWeek } from "./isValidFiscalExtraWeek.js";
+import { isValidFiscalPattern } from "./isValidFiscalPattern.js";
+import { isValidFiscalYearLabel } from "./isValidFiscalYearLabel.js";
+/**
+ * Return true when `calendar` is a `FiscalCalendar` that `getFiscalPeriod` accepts.
+ *
+ * - `pattern` must be `"4-5-4"`, `"4-4-5"` or `"5-4-4"`.
+ * - `yearEndsOn` must be a plain ISO date. A datetime or a date that does not exist is not.
+ * - `extraWeek` must be `"firstPeriod"` or `"lastPeriod"`, and `yearLabel` must be
+ *   `"startYear"`, `"endYear"` or `"majorityYear"`. Both are required: there is no default.
+ * - Extra properties are ignored.
+ * - Returns `false` for non-objects, `null` and arrays.
+ * - `getFiscalPeriod` returns null for a calendar this rejects, the same sentinel it returns
+ *   for an invalid date. Check the calendar here to tell the two apart.
+ *
+ * @param calendar candidate value of any type
+ * @returns boolean indicating whether `getFiscalPeriod` accepts it
+ *
+ * @example isValidFiscalCalendar({ pattern: "4-5-4", yearEndsOn: "2026-01-31", extraWeek: "lastPeriod", yearLabel: "startYear" }) // true
+ * @example isValidFiscalCalendar({ pattern: "4-5-4", yearEndsOn: "2026-01-31" }) // false (the 1.19 shape: no extraWeek or yearLabel)
+ * @example isValidFiscalCalendar({ pattern: "4-5-4", yearEndsOn: "2026-02-30", extraWeek: "lastPeriod", yearLabel: "startYear" }) // false
+ * @example isValidFiscalCalendar("4-5-4") // false
+ * @example isValidFiscalCalendar([]) // false
+ */
+export function isValidFiscalCalendar(calendar) {
+    try {
+        if (!isObject(calendar) || Array.isArray(calendar)) {
+            return false;
+        }
+        const { pattern, yearEndsOn, extraWeek, yearLabel } = calendar;
+        return (isValidFiscalPattern(pattern) &&
+            typeof yearEndsOn === "string" &&
+            isValidDate(yearEndsOn) &&
+            isValidFiscalExtraWeek(extraWeek) &&
+            isValidFiscalYearLabel(yearLabel));
+    }
+    catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
+        return false;
+    }
+}

package/dist/calendar/validate/isValidFiscalExtraWeek.d.ts

@@ -0,0 +1,19 @@
+import type { FiscalExtraWeek } from "../../types/index.js";
+/**
+ * Return true when `value` is a valid FiscalExtraWeek: the period a 53rd week is added to.
+ *
+ * - Valid values are `"firstPeriod"` and `"lastPeriod"`. The ONS retail trading periods (UK)
+ *   add a five-week January; the NRF 4-5-4 calendar (US) adds the week to the end.
+ * - Accepts any input type and returns false for non-string values.
+ * - Use it to narrow a value read from config, an env var or a form before building a
+ *   `FiscalCalendar`.
+ *
+ * @param value candidate value of any type
+ * @returns boolean indicating validity
+ *
+ * @example isValidFiscalExtraWeek("firstPeriod") // true
+ * @example isValidFiscalExtraWeek("lastPeriod") // true
+ * @example isValidFiscalExtraWeek("lastQuarter") // false
+ * @example isValidFiscalExtraWeek(12) // false
+ */
+export declare function isValidFiscalExtraWeek(value: unknown): value is FiscalExtraWeek;

package/dist/calendar/validate/isValidFiscalExtraWeek.js

@@ -0,0 +1,23 @@
+/**
+ * Return true when `value` is a valid FiscalExtraWeek: the period a 53rd week is added to.
+ *
+ * - Valid values are `"firstPeriod"` and `"lastPeriod"`. The ONS retail trading periods (UK)
+ *   add a five-week January; the NRF 4-5-4 calendar (US) adds the week to the end.
+ * - Accepts any input type and returns false for non-string values.
+ * - Use it to narrow a value read from config, an env var or a form before building a
+ *   `FiscalCalendar`.
+ *
+ * @param value candidate value of any type
+ * @returns boolean indicating validity
+ *
+ * @example isValidFiscalExtraWeek("firstPeriod") // true
+ * @example isValidFiscalExtraWeek("lastPeriod") // true
+ * @example isValidFiscalExtraWeek("lastQuarter") // false
+ * @example isValidFiscalExtraWeek(12) // false
+ */
+export function isValidFiscalExtraWeek(value) {
+    if (typeof value !== "string") {
+        return false;
+    }
+    return value === "firstPeriod" || value === "lastPeriod";
+}