@northguild/gmt 1.17.0 → 1.19.0

package/dist/calendar/hours/addOperatingTime.js

@@ -0,0 +1,65 @@
+import { parseInstantNanoseconds } from "../../internal/index.js";
+import { instantAfterOpenTime, instantText, parseOpenTimeAmount, parseOperatingSchedule, parseScheduleDisambiguation, parseSearchHorizon, } from "../../internal/operatingSchedule.js";
+/**
+ * Return the instant at which `duration` of open time has elapsed since `start`: the deadline
+ * of a service level measured in working hours.
+ *
+ * - The earliest instant `X` such that `operatingTimeBetween(start, X, schedule)` equals
+ *   `duration`. The clock stops while the schedule is closed and resumes when it reopens, so an
+ *   eight-hour SLA raised at Friday 16:00 on a 09:00–17:00 weekday desk falls due on Monday at
+ *   16:00. A deadline that lands exactly on a closing time is that closing instant, not the next
+ *   opening.
+ * - `duration` is hours and smaller units (`"PT8H"`, `"PT90M"`). A duration with days, weeks,
+ *   months or years returns `""`: `P1D` of open time could mean 24 open hours or one working
+ *   day, and GMT does not guess. `"PT0S"` returns `start` itself, in UTC.
+ * - Returns `""` when the deadline would fall past the search horizon, rather than searching
+ *   forever.
+ * - Holidays and overrides apply as in `operatingIntervals`.
+ * - Returns `""` on invalid input: an invalid instant, duration or `OperatingSchedule`, a
+ *   negative `duration`, 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 start ISO 8601 instant string where the clock starts
+ * @param duration ISO 8601 duration of open time, hours and smaller units (e.g. "PT8H")
+ * @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 past the horizon or on invalid input
+ *
+ * @example addOperatingTime("2024-06-14T20:00:00Z", "PT2H", { timeZone: "America/New_York", weekly: { 1: [{ from: "09:00", to: "17:00" }], 5: [{ from: "09:00", to: "17:00" }] } }) // "2024-06-17T14:00:00Z" — Friday 16:00 to Monday 10:00 local
+ * @example addOperatingTime("2024-06-14T20:00:00Z", "PT1H", { timeZone: "America/New_York", weekly: { 5: [{ from: "09:00", to: "17:00" }] } }) // "2024-06-14T21:00:00Z" — due at closing, not at the next opening
+ * @example addOperatingTime("2024-06-14T20:00:00Z", "PT2H", { timeZone: "America/New_York", weekly: { 1: [{ from: "09:00", to: "17:00" }], 5: [{ from: "09:00", to: "17:00" }] } }, { within: "P1D" }) // "" — past the horizon
+ * @example addOperatingTime("2024-06-15T12:00:00Z", "PT0S", { timeZone: "UTC", weekly: {} }) // "2024-06-15T12:00:00Z"
+ * @example addOperatingTime("2024-06-14T20:00:00Z", "P1D", { timeZone: "UTC", weekly: { 5: [{ from: "09:00", to: "17:00" }] } }) // "" — days are not open time
+ * @example addOperatingTime("2024-06-14T20:00:00Z", "-PT1H", { timeZone: "UTC", weekly: { 5: [{ from: "09:00", to: "17:00" }] } }) // ""
+ */
+export function addOperatingTime(start, duration, schedule, optionsArg) {
+    try {
+        const disambiguation = parseScheduleDisambiguation(optionsArg);
+        const resolved = parseOperatingSchedule(schedule);
+        const from = parseInstantNanoseconds(start);
+        const amount = parseOpenTimeAmount(duration);
+        if (disambiguation === null ||
+            resolved === null ||
+            from === null ||
+            amount === null) {
+            return "";
+        }
+        const horizon = parseSearchHorizon(from, optionsArg?.within, resolved.frame);
+        if (horizon === null) {
+            return "";
+        }
+        const answer = instantAfterOpenTime(resolved, from, amount, 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/index.d.ts

@@ -0,0 +1,7 @@
+export * from "./addOperatingTime.js";
+export * from "./isOpenAt.js";
+export * from "./nextCloseAt.js";
+export * from "./nextOpenAt.js";
+export * from "./operatingIntervals.js";
+export * from "./operatingTimeBetween.js";
+export * from "./recurringWindows.js";

package/dist/calendar/hours/index.js

@@ -0,0 +1,7 @@
+export * from "./addOperatingTime.js";
+export * from "./isOpenAt.js";
+export * from "./nextCloseAt.js";
+export * from "./nextOpenAt.js";
+export * from "./operatingIntervals.js";
+export * from "./operatingTimeBetween.js";
+export * from "./recurringWindows.js";

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

@@ -0,0 +1,45 @@
+import type { Disambiguation, OperatingSchedule } from "../../types/index.js";
+/**
+ * Return true when `schedule` is open at the instant `isoString`.
+ *
+ * - Open means inside one of the half-open intervals `operatingIntervals` returns: an opening
+ *   instant is open, a closing instant is closed. Where one window ends as the next begins, the
+ *   schedule stays open.
+ * - A window belongs to the date it starts on, so a Friday 23:00–06:00 window is open at 01:00
+ *   on Saturday even when Saturday is a holiday.
+ * - `isoString` is an instant: an offset (`Z`, `±HH:MM`) is required, and a bracketed zone
+ *   never supplies the zone — the schedule's own zone reads the windows. Only its instant is
+ *   read, a minute-rounded offset as the bracketed zone's real one (see `isValidInstant`).
+ * - 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-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-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 declare function isOpenAt(isoString: 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 `false` when a window with such an edge is the only one that
+     * could be open at `isoString`.
+     *
+     * @defaultValue `"compatible"`, Temporal's default.
+     */
+    disambiguation?: Disambiguation;
+}): boolean;

package/dist/calendar/hours/isOpenAt.js

@@ -0,0 +1,50 @@
+import { parseInstantNanoseconds } from "../../internal/index.js";
+import { firstOpenInstant, parseOperatingSchedule, parseScheduleDisambiguation, } from "../../internal/operatingSchedule.js";
+/**
+ * Return true when `schedule` is open at the instant `isoString`.
+ *
+ * - Open means inside one of the half-open intervals `operatingIntervals` returns: an opening
+ *   instant is open, a closing instant is closed. Where one window ends as the next begins, the
+ *   schedule stays open.
+ * - A window belongs to the date it starts on, so a Friday 23:00–06:00 window is open at 01:00
+ *   on Saturday even when Saturday is a holiday.
+ * - `isoString` is an instant: an offset (`Z`, `±HH:MM`) is required, and a bracketed zone
+ *   never supplies the zone — the schedule's own zone reads the windows. Only its instant is
+ *   read, a minute-rounded offset as the bracketed zone's real one (see `isValidInstant`).
+ * - 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-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-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 {
+        const disambiguation = parseScheduleDisambiguation(optionsArg);
+        const resolved = parseOperatingSchedule(schedule);
+        const at = parseInstantNanoseconds(isoString);
+        if (disambiguation === null || resolved === null || at === null) {
+            return false;
+        }
+        return firstOpenInstant(resolved, at, at, disambiguation) === at;
+    }
+    catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
+        return false;
+    }
+}

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

@@ -0,0 +1,55 @@
+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.
+ * - **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-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,57 @@
+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.
+ * - **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-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.frame);
+        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,51 @@
+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.
+ * - **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-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,53 @@
+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.
+ * - **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-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.frame);
+        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,48 @@
+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.
+ * - **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: "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,57 @@
+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.
+ * - **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: "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,45 @@
+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.
+ * - **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)
+ * @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,54 @@
+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.
+ * - **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)
+ * @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 "";
+    }
+}