@northguild/gmt 1.16.0 → 1.18.0

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

@@ -0,0 +1,49 @@
+import type { Disambiguation, OperatingSchedule } from "../../types/index.js";
+/**
+ * Return the first instant at or after `isoString` that `schedule` is closed, as a UTC instant.
+ *
+ * - Open at `isoString`: returns the end of the open interval holding it — when the gate
+ *   closes. Windows that touch are one interval, so a schedule open 00:00–00:00 every day
+ *   closes only where a day has no window.
+ * - Already closed at `isoString`: returns `isoString` itself, in UTC. Pair it with
+ *   `nextOpenAt` to find the next open interval: `nextCloseAt(nextOpenAt(t, s), s)`.
+ * - Returns `""` when the schedule stays open past the search horizon — a schedule open around
+ *   the clock never closes.
+ * - Holidays and overrides apply as in `operatingIntervals`.
+ * - `isoString` is an instant: an offset (`Z`, `±HH:MM`) is required.
+ * - 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.
+ *
+ * @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-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
+ * @example nextCloseAt("invalid", { timeZone: "UTC", weekly: {} }) // ""
+ */
+export declare function nextCloseAt(isoString: string, schedule: OperatingSchedule, optionsArg?: {
+    /**
+     * How far after `isoString` the search may go, as a non-negative ISO 8601 duration added in the
+     * schedule's zone, so `"P1D"` is one local day. A closing exactly at that horizon counts, and a
+     * horizon past Temporal's last instant stops there.
+     *
+     * @defaultValue `"P1Y"`
+     */
+    within?: string;
+    /**
+     * How a window edge in a repeated or skipped local hour becomes an instant, as `resolveLocal`
+     * resolves it. `"compatible"` takes the earlier instant of a repeated fall-back hour and the
+     * later one of a skipped spring-forward hour, and `"earlier"` and `"later"` take that side in
+     * both cases. `"reject"` returns `""` when a window with such an edge could keep the schedule
+     * open past the answer.
+     *
+     * @defaultValue `"compatible"`, Temporal's default.
+     */
+    disambiguation?: Disambiguation;
+}): string;

package/dist/calendar/hours/nextCloseAt.js

@@ -0,0 +1,51 @@
+import { parseInstantNanoseconds } from "../../internal/index.js";
+import { firstClosedInstant, instantText, parseOperatingSchedule, parseScheduleDisambiguation, parseSearchHorizon, } from "../../internal/operatingSchedule.js";
+/**
+ * Return the first instant at or after `isoString` that `schedule` is closed, as a UTC instant.
+ *
+ * - Open at `isoString`: returns the end of the open interval holding it — when the gate
+ *   closes. Windows that touch are one interval, so a schedule open 00:00–00:00 every day
+ *   closes only where a day has no window.
+ * - Already closed at `isoString`: returns `isoString` itself, in UTC. Pair it with
+ *   `nextOpenAt` to find the next open interval: `nextCloseAt(nextOpenAt(t, s), s)`.
+ * - Returns `""` when the schedule stays open past the search horizon — a schedule open around
+ *   the clock never closes.
+ * - Holidays and overrides apply as in `operatingIntervals`.
+ * - `isoString` is an instant: an offset (`Z`, `±HH:MM`) is required.
+ * - 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.
+ *
+ * @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-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
+ * @example nextCloseAt("invalid", { timeZone: "UTC", weekly: {} }) // ""
+ */
+export function nextCloseAt(isoString, schedule, optionsArg) {
+    try {
+        const disambiguation = parseScheduleDisambiguation(optionsArg);
+        const resolved = parseOperatingSchedule(schedule);
+        const from = parseInstantNanoseconds(isoString);
+        if (disambiguation === null || resolved === null || from === null) {
+            return "";
+        }
+        const horizon = parseSearchHorizon(from, optionsArg?.within, resolved.timeZone);
+        if (horizon === null) {
+            return "";
+        }
+        const answer = firstClosedInstant(resolved, from, horizon, disambiguation);
+        return typeof answer === "bigint" ? instantText(answer) : "";
+    }
+    catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
+        return "";
+    }
+}

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

@@ -0,0 +1,45 @@
+import type { Disambiguation, OperatingSchedule } from "../../types/index.js";
+/**
+ * Return the first instant at or after `isoString` that `schedule` is open, as a UTC instant.
+ *
+ * - Already open at `isoString`: returns `isoString` itself, in UTC. Otherwise returns the start
+ *   of the next open interval — the moment a gate opens, or a notice can be tendered.
+ * - Returns `""` when the schedule does not open within the search horizon, rather than
+ *   searching forever.
+ * - Holidays and overrides apply as in `operatingIntervals`.
+ * - `isoString` is an instant: an offset (`Z`, `±HH:MM`) is required.
+ * - 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.
+ *
+ * @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-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" }) // ""
+ */
+export declare function nextOpenAt(isoString: string, schedule: OperatingSchedule, optionsArg?: {
+    /**
+     * How far after `isoString` the search may go, as a non-negative ISO 8601 duration added in the
+     * schedule's zone, so `"P1D"` is one local day. An opening exactly at that horizon counts, and a
+     * horizon past Temporal's last instant stops there.
+     *
+     * @defaultValue `"P1Y"`
+     */
+    within?: string;
+    /**
+     * How a window edge in a repeated or skipped local hour becomes an instant, as `resolveLocal`
+     * resolves it. `"compatible"` takes the earlier instant of a repeated fall-back hour and the
+     * later one of a skipped spring-forward hour, and `"earlier"` and `"later"` take that side in
+     * both cases. `"reject"` returns `""` when a window with such an edge could open before the
+     * answer.
+     *
+     * @defaultValue `"compatible"`, Temporal's default.
+     */
+    disambiguation?: Disambiguation;
+}): string;

package/dist/calendar/hours/nextOpenAt.js

@@ -0,0 +1,47 @@
+import { parseInstantNanoseconds } from "../../internal/index.js";
+import { firstOpenInstant, instantText, parseOperatingSchedule, parseScheduleDisambiguation, parseSearchHorizon, } from "../../internal/operatingSchedule.js";
+/**
+ * Return the first instant at or after `isoString` that `schedule` is open, as a UTC instant.
+ *
+ * - Already open at `isoString`: returns `isoString` itself, in UTC. Otherwise returns the start
+ *   of the next open interval — the moment a gate opens, or a notice can be tendered.
+ * - Returns `""` when the schedule does not open within the search horizon, rather than
+ *   searching forever.
+ * - Holidays and overrides apply as in `operatingIntervals`.
+ * - `isoString` is an instant: an offset (`Z`, `±HH:MM`) is required.
+ * - 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.
+ *
+ * @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-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" }) // ""
+ */
+export function nextOpenAt(isoString, schedule, optionsArg) {
+    try {
+        const disambiguation = parseScheduleDisambiguation(optionsArg);
+        const resolved = parseOperatingSchedule(schedule);
+        const from = parseInstantNanoseconds(isoString);
+        if (disambiguation === null || resolved === null || from === null) {
+            return "";
+        }
+        const horizon = parseSearchHorizon(from, optionsArg?.within, resolved.timeZone);
+        if (horizon === null) {
+            return "";
+        }
+        const answer = firstOpenInstant(resolved, from, horizon, disambiguation);
+        return typeof answer === "bigint" ? instantText(answer) : "";
+    }
+    catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
+        return "";
+    }
+}

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

@@ -0,0 +1,43 @@
+import type { Disambiguation, Interval, OperatingSchedule } from "../../types/index.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.
+ *
+ * - Works date by date in `schedule.timeZone`. A date listed in `holidays` has no windows; a
+ *   date with an override has exactly the override's windows, holiday or not. `holidays` may be
+ *   a `BusinessCalendar`, whose `holidays` are read.
+ * - A window belongs to the date it starts on, so a holiday or override on Friday removes or
+ *   replaces a Friday 23:00–06:00 window, and one on Saturday leaves it alone.
+ * - Window edges are local wall times; `recurringWindows` states the window rules in full.
+ * - The result is clipped to `range` (half-open), sorted, and merged where windows overlap or
+ *   touch. Endpoints are UTC instants ending in `Z`, except a clipped edge, which is `range`'s
+ *   own string.
+ * - `[]` is both a legitimate result (closed throughout, or an empty `range`) and the sentinel.
+ * - Returns `[]` when `schedule` is not a valid `OperatingSchedule` (a weekday key other than
+ *   `"1"`–`"7"`, a malformed window, an invalid zone, holiday or override date, or two overrides
+ *   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.
+ *
+ * @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: "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" }) // []
+ */
+export declare function operatingIntervals(schedule: OperatingSchedule, range: Interval, optionsArg?: {
+    /**
+     * How a window edge in a repeated or skipped local hour becomes an instant, as `resolveLocal`
+     * resolves it. `"compatible"` takes the earlier instant of a repeated fall-back hour and the
+     * later one of a skipped spring-forward hour, and `"earlier"` and `"later"` take that side in
+     * both cases. `"reject"` returns `[]` when a window with such an edge reaches the range.
+     *
+     * @defaultValue `"compatible"`, Temporal's default.
+     */
+    disambiguation?: Disambiguation;
+}): Interval[];

package/dist/calendar/hours/operatingIntervals.js

@@ -0,0 +1,52 @@
+import { parseIntervalNanoseconds } from "../../internal/index.js";
+import { parseOperatingSchedule, parseScheduleDisambiguation, 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.
+ *
+ * - Works date by date in `schedule.timeZone`. A date listed in `holidays` has no windows; a
+ *   date with an override has exactly the override's windows, holiday or not. `holidays` may be
+ *   a `BusinessCalendar`, whose `holidays` are read.
+ * - A window belongs to the date it starts on, so a holiday or override on Friday removes or
+ *   replaces a Friday 23:00–06:00 window, and one on Saturday leaves it alone.
+ * - Window edges are local wall times; `recurringWindows` states the window rules in full.
+ * - The result is clipped to `range` (half-open), sorted, and merged where windows overlap or
+ *   touch. Endpoints are UTC instants ending in `Z`, except a clipped edge, which is `range`'s
+ *   own string.
+ * - `[]` is both a legitimate result (closed throughout, or an empty `range`) and the sentinel.
+ * - Returns `[]` when `schedule` is not a valid `OperatingSchedule` (a weekday key other than
+ *   `"1"`–`"7"`, a malformed window, an invalid zone, holiday or override date, or two overrides
+ *   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.
+ *
+ * @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: "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" }) // []
+ */
+export function operatingIntervals(schedule, range, optionsArg) {
+    try {
+        const disambiguation = parseScheduleDisambiguation(optionsArg);
+        const resolved = parseOperatingSchedule(schedule);
+        const bounds = parseIntervalNanoseconds(range);
+        if (disambiguation === null || resolved === null || bounds === null) {
+            return [];
+        }
+        const runs = scheduleRunsWithin(resolved, bounds, disambiguation);
+        return runs === null
+            ? []
+            : runs.map((run) => ({ start: run.startText, end: run.endText }));
+    }
+    catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
+        return [];
+    }
+}

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

@@ -0,0 +1,40 @@
+import type { Disambiguation, OperatingSchedule } from "../../types/index.js";
+/**
+ * Return how much open time `schedule` has between two instants, as an exact ISO duration.
+ *
+ * - The open time in the half-open range `[start, end)`: the length of its intersection with
+ *   `operatingIntervals(schedule, { start, end })`, summed as `sumIntervals` sums. A support
+ *   ticket raised Friday 16:00 and answered Monday 10:00 on a 09:00–17:00 weekday desk has
+ *   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.
+ * - 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.
+ *
+ * @param start ISO 8601 instant string where the clock starts (inclusive)
+ * @param end ISO 8601 instant string where the clock stops (exclusive)
+ * @param schedule `{ timeZone, weekly, holidays?, overrides? }` operating schedule
+ * @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-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-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
+ */
+export declare function operatingTimeBetween(start: string, end: string, schedule: OperatingSchedule, optionsArg?: {
+    /**
+     * How a window edge in a repeated or skipped local hour becomes an instant, as `resolveLocal`
+     * resolves it. `"compatible"` takes the earlier instant of a repeated fall-back hour and the
+     * later one of a skipped spring-forward hour, and `"earlier"` and `"later"` take that side in
+     * both cases. `"reject"` returns `""` when a window with such an edge reaches the range.
+     *
+     * @defaultValue `"compatible"`, Temporal's default.
+     */
+    disambiguation?: Disambiguation;
+}): string;

package/dist/calendar/hours/operatingTimeBetween.js

@@ -0,0 +1,49 @@
+import { formatHourDuration, parseIntervalNanoseconds } from "../../internal/index.js";
+import { parseOperatingSchedule, parseScheduleDisambiguation, scheduleRunsWithin, } from "../../internal/operatingSchedule.js";
+/**
+ * Return how much open time `schedule` has between two instants, as an exact ISO duration.
+ *
+ * - The open time in the half-open range `[start, end)`: the length of its intersection with
+ *   `operatingIntervals(schedule, { start, end })`, summed as `sumIntervals` sums. A support
+ *   ticket raised Friday 16:00 and answered Monday 10:00 on a 09:00–17:00 weekday desk has
+ *   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.
+ * - 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.
+ *
+ * @param start ISO 8601 instant string where the clock starts (inclusive)
+ * @param end ISO 8601 instant string where the clock stops (exclusive)
+ * @param schedule `{ timeZone, weekly, holidays?, overrides? }` operating schedule
+ * @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-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-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
+ */
+export function operatingTimeBetween(start, end, schedule, optionsArg) {
+    try {
+        const disambiguation = parseScheduleDisambiguation(optionsArg);
+        const resolved = parseOperatingSchedule(schedule);
+        const range = parseIntervalNanoseconds({ start, end });
+        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));
+    }
+    catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
+        return "";
+    }
+}

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

@@ -0,0 +1,61 @@
+import type { Disambiguation, Interval, OperatingSchedule } from "../../types/index.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.
+ *
+ * - `weekly` maps ISO weekdays (1 = Monday … 7 = Sunday) to `LocalWindow`s of wall time. A
+ *   window whose `to` is at or before its `from` wraps past midnight and belongs to the date it
+ *   starts on: `{ from: "23:00", to: "06:00" }` under 5 is Friday 23:00 to Saturday 06:00, and
+ *   `{ from: "00:00", to: "00:00" }` is the whole day. No holidays or overrides; see
+ *   `operatingIntervals` for those.
+ * - Each window edge is a local wall time resolved with `resolveLocal`. An edge in a skipped
+ *   spring-forward hour is shifted by the gap: forward, or back when it is read `"earlier"` (TC39
+ *   DisambiguatePossibleEpochNanoseconds), so in a zone that skips midnight a date's early
+ *   window can open on the previous local date, before the date's own first instant; it still
+ *   belongs to its own date.
+ * - A window "reaches the range" for `"reject"` when the widest span it could cover (its `from`
+ *   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
+ *   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.
+ * - The result is clipped to `range` (half-open), sorted, and merged where windows overlap or
+ *   touch, so a run of whole-day windows is one interval. Endpoints are UTC instants ending in
+ *   `Z`, except a clipped edge, which is `range`'s own string.
+ * - Local dates follow the zone's real days: a date the zone deleted (`Pacific/Apia` skipped
+ *   2011-12-30) has no windows, and a date re-entered after a fall-back is counted once.
+ * - `[]` is both a legitimate result (closed throughout, or an empty `range`) and the sentinel.
+ * - Returns `[]` when `weekly` has a key other than `"1"`–`"7"` or a malformed window, when
+ *   `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.
+ *
+ * @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 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({ 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({ 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") // []
+ */
+export declare function recurringWindows(weekly: OperatingSchedule["weekly"], range: Interval, timeZone: string, optionsArg?: {
+    /**
+     * How a window edge in a repeated or skipped local hour becomes an instant, as `resolveLocal`
+     * resolves it. `"compatible"` takes the earlier instant of a repeated fall-back hour and the
+     * later one of a skipped spring-forward hour, and `"earlier"` and `"later"` take that side in
+     * both cases. `"reject"` returns `[]` when a window with such an edge reaches the range.
+     *
+     * @defaultValue `"compatible"`, Temporal's default.
+     */
+    disambiguation?: Disambiguation;
+}): Interval[];

package/dist/calendar/hours/recurringWindows.js

@@ -0,0 +1,80 @@
+import { parseIntervalNanoseconds } from "../../internal/index.js";
+import { parseScheduleDisambiguation, parseWeeklyPattern, scheduleRunsWithin, } from "../../internal/operatingSchedule.js";
+import { isValidTimeZone } from "../../zoned/validate/index.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.
+ *
+ * - `weekly` maps ISO weekdays (1 = Monday … 7 = Sunday) to `LocalWindow`s of wall time. A
+ *   window whose `to` is at or before its `from` wraps past midnight and belongs to the date it
+ *   starts on: `{ from: "23:00", to: "06:00" }` under 5 is Friday 23:00 to Saturday 06:00, and
+ *   `{ from: "00:00", to: "00:00" }` is the whole day. No holidays or overrides; see
+ *   `operatingIntervals` for those.
+ * - Each window edge is a local wall time resolved with `resolveLocal`. An edge in a skipped
+ *   spring-forward hour is shifted by the gap: forward, or back when it is read `"earlier"` (TC39
+ *   DisambiguatePossibleEpochNanoseconds), so in a zone that skips midnight a date's early
+ *   window can open on the previous local date, before the date's own first instant; it still
+ *   belongs to its own date.
+ * - A window "reaches the range" for `"reject"` when the widest span it could cover (its `from`
+ *   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
+ *   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.
+ * - The result is clipped to `range` (half-open), sorted, and merged where windows overlap or
+ *   touch, so a run of whole-day windows is one interval. Endpoints are UTC instants ending in
+ *   `Z`, except a clipped edge, which is `range`'s own string.
+ * - Local dates follow the zone's real days: a date the zone deleted (`Pacific/Apia` skipped
+ *   2011-12-30) has no windows, and a date re-entered after a fall-back is counted once.
+ * - `[]` is both a legitimate result (closed throughout, or an empty `range`) and the sentinel.
+ * - Returns `[]` when `weekly` has a key other than `"1"`–`"7"` or a malformed window, when
+ *   `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.
+ *
+ * @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 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({ 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({ 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") // []
+ */
+export function recurringWindows(weekly, range, timeZone, optionsArg) {
+    try {
+        const disambiguation = parseScheduleDisambiguation(optionsArg);
+        const weeklyWindows = parseWeeklyPattern(weekly);
+        const bounds = parseIntervalNanoseconds(range);
+        if (disambiguation === null ||
+            weeklyWindows === null ||
+            bounds === null ||
+            typeof timeZone !== "string" ||
+            !isValidTimeZone(timeZone)) {
+            return [];
+        }
+        const runs = scheduleRunsWithin({
+            timeZone,
+            weekly: weeklyWindows,
+            holidays: new Set(),
+            overrides: new Map(),
+        }, bounds, disambiguation);
+        return runs === null
+            ? []
+            : runs.map((run) => ({ start: run.startText, end: run.endText }));
+    }
+    catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
+        return [];
+    }
+}

package/dist/calendar/index.d.ts

@@ -1,4 +1,5 @@
 export * from "@js-temporal/polyfill";
 export * from "./business/index.js";
 export * from "./calculate/index.js";
+export * from "./hours/index.js";
 export * from "./validate/index.js";

package/dist/calendar/index.js

@@ -2,4 +2,5 @@
 export * from "@js-temporal/polyfill";
 export * from "./business/index.js";
 export * from "./calculate/index.js";
+export * from "./hours/index.js";
 export * from "./validate/index.js";

package/dist/duration/calculate/durationAs.d.ts

@@ -7,16 +7,12 @@ import type { DateTimeDurationUnit, DurationRelativeTo } from "../../types/index
  *   durationAs("P1DT2H30M", "hours") is 26.5, not the 2 that `getDurationUnit` reads.
  * - The result is fractional, not rounded: durationAs("P1DT2H30M", "days") is
  *   1.1041666666666667. Round it yourself, or reach for `normalizeDuration` instead.
- * - `relativeTo` is required whenever a calendar unit (year/month/week) is involved, in
- *   *either* direction — as the requested `unit`, or because the input duration already has
- *   a nonzero year/month/week component. Without it, returns null. This is the same
- *   documented gap `normalizeDuration` (A3) carries; `addDuration`/`subtractDuration` (A2)
- *   have it worse still, since Temporal gives them no `relativeTo` option at all.
+ * - The calendar-unit rule of `relativeTo` is the same one `normalizeDuration` (A3) carries;
+ *   `addDuration`/`subtractDuration` (A2) have it worse still, since Temporal gives them no
+ *   `relativeTo` option at all.
  * - The requested-unit half of that rule bites even on day/time-only input: "P1DT2H30M" has
  *   no calendar component, yet durationAs("P1DT2H30M", "weeks") is still null — a week is a
  *   calendar quantity to Temporal regardless of what it is being measured from.
- * - `relativeTo` changes the answer for non-calendar units too when it names a zoned instant:
- *   a day spanning a DST spring-forward transition totals 23 hours, not 24.
  * - A zoned `relativeTo` string resolves its wall time with disambiguation "compatible" and
  *   offset "reject", as Temporal does: an ambiguous wall time takes the earlier instant, a
  *   nonexistent one the later instant, and an offset that does not match the zone returns null.
@@ -39,7 +35,7 @@ import type { DateTimeDurationUnit, DurationRelativeTo } from "../../types/index
  *
  * @param value ISO 8601 duration string
  * @param unit DateTimeDurationUnit to total into ("years" | "months" | "weeks" | "days" | "hours" | "minutes" | "seconds" | "milliseconds" | "microseconds" | "nanoseconds", or the singular name)
- * @param options optional: { relativeTo } — anchor date/instant, required for any calendar unit
+ * @param options The anchor calendar units are measured from
  * @returns the fractional total in `unit`, or null on invalid input
  *
  * @example durationAs("P1DT2H30M", "hours") // 26.5
@@ -58,5 +54,14 @@ import type { DateTimeDurationUnit, DurationRelativeTo } from "../../types/index
  * @example durationAs("P1M", "days", { relativeTo: "2024-02-10T00:00:00[u-ca=hebrew]" }) // 30 (a date-time without a zone reads as its date, as Temporal reads relativeTo)
  */
 export declare function durationAs(value: string, unit: DateTimeDurationUnit | Temporal.DateTimeUnit, options?: {
+    /**
+     * The date or zoned date-time the duration is measured from. It is required whenever a year,
+     * month or week is involved, as the `unit` asked for or as a nonzero field of the duration.
+     * With a zoned value, days follow that zone's clock changes, so a day spanning a
+     * spring-forward transition totals 23 hours.
+     *
+     * @defaultValue None. Days are 24 hours, and a duration or `unit` that involves a year, month
+     * or week returns `null`.
+     */
     relativeTo?: DurationRelativeTo;
 }): number | null;