@northguild/gmt 1.16.0 → 1.18.0

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

@@ -15,8 +15,8 @@ import type { ZoneBucketUnit } from "../../types/index.js";
  * - The range is half-open: an `end` landing exactly on a boundary does not open that bucket.
  *   A zero-length range mid-bucket still returns the one bucket holding it; on a boundary it
  *   returns `[]`.
- * - Both endpoints are read in `timeZone`. Any bracketed zone they carry is ignored, as in
- *   `floorToZone`.
+ * - Both endpoints are read in `timeZone`. A bracketed zone they carry never supplies the
+ *   zone, as in `floorToZone`.
  * - Weeks start on Monday (ISO 8601). `unit` is the same four-unit set `floorToZone` takes,
  *   singular or plural, which `isValidZoneBucketUnit` narrows.
  * - A local boundary that does not exist is not invented: the day Samoa deleted crossing the
@@ -33,7 +33,7 @@ import type { ZoneBucketUnit } from "../../types/index.js";
  * @param start ISO 8601 instant string for the range start (inclusive)
  * @param end ISO 8601 instant string for the range end (exclusive)
  * @param unit bucket unit ("hour" | "day" | "week" | "month", or its plural)
- * @param timeZone IANA timeZone identifier the buckets are computed in
+ * @param timeZone IANA name or UTC offset the buckets are computed in
  * @returns array of UTC instant strings ending in "Z", or [] on invalid input
  *
  * @example bucketRange("2024-06-15T03:00:00Z", "2024-06-17T03:00:00Z", "day", "America/New_York") // ["2024-06-14T04:00:00Z", "2024-06-15T04:00:00Z", "2024-06-16T04:00:00Z"]

package/dist/calendar/calculate/bucketRange.js

@@ -1,5 +1,5 @@
 import { Temporal } from "@js-temporal/polyfill";
-import { nextZonedBucketStart, zonedNextTransition, zonedUnitStart, } from "../../internal/index.js";
+import { instantFrom, nextZonedBucketStart, zonedNextTransition, zonedUnitStart, } from "../../internal/index.js";
 import { isValidInstant } from "../../precision/validate/index.js";
 import { isValidTimeZone } from "../../zoned/validate/index.js";
 import { isValidZoneBucketUnit } from "../validate/index.js";
@@ -93,8 +93,8 @@ function nextBucketStartWithinRange(current, unit) {
  * - The range is half-open: an `end` landing exactly on a boundary does not open that bucket.
  *   A zero-length range mid-bucket still returns the one bucket holding it; on a boundary it
  *   returns `[]`.
- * - Both endpoints are read in `timeZone`. Any bracketed zone they carry is ignored, as in
- *   `floorToZone`.
+ * - Both endpoints are read in `timeZone`. A bracketed zone they carry never supplies the
+ *   zone, as in `floorToZone`.
  * - Weeks start on Monday (ISO 8601). `unit` is the same four-unit set `floorToZone` takes,
  *   singular or plural, which `isValidZoneBucketUnit` narrows.
  * - A local boundary that does not exist is not invented: the day Samoa deleted crossing the
@@ -111,7 +111,7 @@ function nextBucketStartWithinRange(current, unit) {
  * @param start ISO 8601 instant string for the range start (inclusive)
  * @param end ISO 8601 instant string for the range end (exclusive)
  * @param unit bucket unit ("hour" | "day" | "week" | "month", or its plural)
- * @param timeZone IANA timeZone identifier the buckets are computed in
+ * @param timeZone IANA name or UTC offset the buckets are computed in
  * @returns array of UTC instant strings ending in "Z", or [] on invalid input
  *
  * @example bucketRange("2024-06-15T03:00:00Z", "2024-06-17T03:00:00Z", "day", "America/New_York") // ["2024-06-14T04:00:00Z", "2024-06-15T04:00:00Z", "2024-06-16T04:00:00Z"]
@@ -134,8 +134,8 @@ export function bucketRange(start, end, unit, timeZone) {
         return [];
     }
     try {
-        const startZoned = Temporal.Instant.from(start).toZonedDateTimeISO(timeZone);
-        const endZoned = Temporal.Instant.from(end).toZonedDateTimeISO(timeZone);
+        const startZoned = instantFrom(start).toZonedDateTimeISO(timeZone);
+        const endZoned = instantFrom(end).toZonedDateTimeISO(timeZone);
         if (Temporal.ZonedDateTime.compare(startZoned, endZoned) > 0)
             return [];
         if (certainlyExceedsBucketCap(startZoned, endZoned, resolvedUnit))

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

@@ -1,4 +1,4 @@
-import { Temporal } from "@js-temporal/polyfill";
+import type { Temporal } from "@js-temporal/polyfill";
 import type { ZoneBucketUnit } from "../../types/index.js";
 /**
  * Floor an instant to the start of the `unit` containing it **in `timeZone`**, and return
@@ -15,7 +15,9 @@ import type { ZoneBucketUnit } from "../../types/index.js";
  *   can be told apart from a bad instant.
  * - `value` is any instant `isValidInstant` accepts — `Z`, an offset, or a bracketed zone.
  *   Only its instant is read: a bracketed zone in `value` is *not* the zone the boundary is
- *   computed in, `timeZone` is, and the two may differ freely.
+ *   computed in, `timeZone` is, and the two may differ freely. An offset written to the minute
+ *   that is the bracketed zone's sub-minute offset rounded (`-00:45[Africa/Monrovia]`, for
+ *   −00:44:30) names the instant the zone gives, as `isValidInstant` describes.
  * - The boundary is a real instant in the zone, so it survives the days a local boundary does
  *   not exist: a local day whose midnight is skipped by a spring-forward starts at 01:00, and
  *   a wall hour repeated by a fall-back floors to whichever pass `value` was in.
@@ -25,7 +27,7 @@ import type { ZoneBucketUnit } from "../../types/index.js";
  *
  * @param value ISO 8601 instant string (e.g. "2024-06-15T03:00:00Z")
  * @param unit boundary unit ("hour" | "day" | "week" | "month", or its plural)
- * @param timeZone IANA timeZone identifier the boundary is computed in
+ * @param timeZone IANA name or UTC offset the boundary is computed in
  * @returns UTC instant string ending in "Z", or "" on invalid input
  *
  * @example floorToZone("2024-06-15T03:00:00Z", "day", "America/New_York") // "2024-06-14T04:00:00Z" (the 14 June local midnight — the instant is already 14 June there)

package/dist/calendar/calculate/floorToZone.js

@@ -1,5 +1,4 @@
-import { Temporal } from "@js-temporal/polyfill";
-import { zonedUnitStart } from "../../internal/index.js";
+import { instantFrom, zonedUnitStart } from "../../internal/index.js";
 import { isValidInstant } from "../../precision/validate/index.js";
 import { isValidTimeZone } from "../../zoned/validate/index.js";
 import { isValidZoneBucketUnit } from "../validate/index.js";
@@ -19,7 +18,9 @@ import { resolveDateTimeUnit } from "../../internal/resolveDateTimeUnit.js";
  *   can be told apart from a bad instant.
  * - `value` is any instant `isValidInstant` accepts — `Z`, an offset, or a bracketed zone.
  *   Only its instant is read: a bracketed zone in `value` is *not* the zone the boundary is
- *   computed in, `timeZone` is, and the two may differ freely.
+ *   computed in, `timeZone` is, and the two may differ freely. An offset written to the minute
+ *   that is the bracketed zone's sub-minute offset rounded (`-00:45[Africa/Monrovia]`, for
+ *   −00:44:30) names the instant the zone gives, as `isValidInstant` describes.
  * - The boundary is a real instant in the zone, so it survives the days a local boundary does
  *   not exist: a local day whose midnight is skipped by a spring-forward starts at 01:00, and
  *   a wall hour repeated by a fall-back floors to whichever pass `value` was in.
@@ -29,7 +30,7 @@ import { resolveDateTimeUnit } from "../../internal/resolveDateTimeUnit.js";
  *
  * @param value ISO 8601 instant string (e.g. "2024-06-15T03:00:00Z")
  * @param unit boundary unit ("hour" | "day" | "week" | "month", or its plural)
- * @param timeZone IANA timeZone identifier the boundary is computed in
+ * @param timeZone IANA name or UTC offset the boundary is computed in
  * @returns UTC instant string ending in "Z", or "" on invalid input
  *
  * @example floorToZone("2024-06-15T03:00:00Z", "day", "America/New_York") // "2024-06-14T04:00:00Z" (the 14 June local midnight — the instant is already 14 June there)
@@ -52,7 +53,7 @@ export function floorToZone(value, unit, timeZone) {
         return "";
     }
     try {
-        const zoned = Temporal.Instant.from(value).toZonedDateTimeISO(timeZone);
+        const zoned = instantFrom(value).toZonedDateTimeISO(timeZone);
         const start = zonedUnitStart(zoned, resolvedUnit);
         return start ? start.toInstant().toString() : "";
     }

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

@@ -16,11 +16,11 @@ import type { FiscalCalendar } from "../../types/index.js";
  *   Saturday falling exactly on January 31. Passing a published year end from a 53-week year
  *   instead (`"2024-02-03"`) states a different rule, because that date sits three days off
  *   the target the rule is centred on, and yields a different, self-consistent calendar.
- * - `week` is the week of the fiscal year, 1–53, the numbering the NRF publishes. `period` is
- *   1–12. A 53rd week is appended to period 12 — the NRF adds it "to the end of the
- *   calendar", which makes a 4-5-4 year's final quarter 4-5-5.
- * - **`year` is the calendar year the fiscal year starts in**, matching the NRF: fiscal 2023
- *   runs 2023-01-29 to 2024-02-03. Organisations labelling by the end year should add one.
+ * - Weeks are numbered through the fiscal year as the NRF publishes them. A 53rd week is
+ *   appended to period 12 — the NRF adds it "to the end of the calendar" — which makes a 4-5-4
+ *   year's final quarter 4-5-5.
+ * - The `year` label follows the NRF: fiscal 2023 runs 2023-01-29 to 2024-02-03. Organisations
+ *   labelling by the end year should add one.
  * - **`year` is not a unique key for a rule anchored near 1 January.** A 52/53-week year is
  *   364 or 371 days, so it drifts against the calendar, and no label taken from a calendar
  *   year survives that for every anchor. Under `yearEndsOn: "2022-12-31"` — the Saturday
@@ -33,9 +33,10 @@ import type { FiscalCalendar } from "../../types/index.js";
  *   date — which `yearEndsOn` determines, and which is yours to enumerate — not on `year`.
  *   GMT does not invent a label the inputs do not fix.
  * - A `yearEndsOn` month-day that does not exist in a year follows Temporal's
- *   `overflow: "constrain"`: a February 29 rule reads February 28 in common years. A
- *   "month-end" rule (26 CFR 1.441-2 style) would put a February 28 anchor on February 29 in
- *   leap years; this does not — state such a rule with a date that exists every year.
+ *   `overflow: "constrain"`: a February 29 rule reads February 28 in common years. A rule tied
+ *   to the end of a month (the weekday nearest to, or last in, the month's final days) would
+ *   put a February 28 anchor on February 29 in leap years; this does not — state such a rule
+ *   with a date that exists every year.
  * - Whether a fiscal year has 52 or 53 weeks is derived from the gap between its own two
  *   ends, never assumed from a table.
  * - `value` must be zoneless — an ISO date or datetime, as `isValidIsoDateLike` accepts. See
@@ -58,7 +59,19 @@ import type { FiscalCalendar } from "../../types/index.js";
  * @example getFiscalPeriod("invalid", { pattern: "4-5-4", yearEndsOn: "2026-01-31" }) // null
  */
 export declare function getFiscalPeriod(value: string, calendar: FiscalCalendar): {
+    /**
+     * The calendar year the fiscal year starts in, not the year it ends in. Two consecutive fiscal
+     * years can share this label when `yearEndsOn` sits near 1 January.
+     */
     year: number;
+    /**
+     * The period of the fiscal year, 1 through 12. Each period is four or five weeks long as
+     * `calendar.pattern` sets, and a 53rd week belongs to period 12.
+     */
     period: number;
+    /**
+     * The week of the fiscal year, 1 through 52, or 53 in a year with an inserted week. Week 1 starts
+     * on the fiscal year's first day.
+     */
     week: number;
 } | null;

package/dist/calendar/calculate/getFiscalPeriod.js

@@ -21,11 +21,11 @@ const DAYS_PER_WEEK = 7;
  *   Saturday falling exactly on January 31. Passing a published year end from a 53-week year
  *   instead (`"2024-02-03"`) states a different rule, because that date sits three days off
  *   the target the rule is centred on, and yields a different, self-consistent calendar.
- * - `week` is the week of the fiscal year, 1–53, the numbering the NRF publishes. `period` is
- *   1–12. A 53rd week is appended to period 12 — the NRF adds it "to the end of the
- *   calendar", which makes a 4-5-4 year's final quarter 4-5-5.
- * - **`year` is the calendar year the fiscal year starts in**, matching the NRF: fiscal 2023
- *   runs 2023-01-29 to 2024-02-03. Organisations labelling by the end year should add one.
+ * - Weeks are numbered through the fiscal year as the NRF publishes them. A 53rd week is
+ *   appended to period 12 — the NRF adds it "to the end of the calendar" — which makes a 4-5-4
+ *   year's final quarter 4-5-5.
+ * - The `year` label follows the NRF: fiscal 2023 runs 2023-01-29 to 2024-02-03. Organisations
+ *   labelling by the end year should add one.
  * - **`year` is not a unique key for a rule anchored near 1 January.** A 52/53-week year is
  *   364 or 371 days, so it drifts against the calendar, and no label taken from a calendar
  *   year survives that for every anchor. Under `yearEndsOn: "2022-12-31"` — the Saturday
@@ -38,9 +38,10 @@ const DAYS_PER_WEEK = 7;
  *   date — which `yearEndsOn` determines, and which is yours to enumerate — not on `year`.
  *   GMT does not invent a label the inputs do not fix.
  * - A `yearEndsOn` month-day that does not exist in a year follows Temporal's
- *   `overflow: "constrain"`: a February 29 rule reads February 28 in common years. A
- *   "month-end" rule (26 CFR 1.441-2 style) would put a February 28 anchor on February 29 in
- *   leap years; this does not — state such a rule with a date that exists every year.
+ *   `overflow: "constrain"`: a February 29 rule reads February 28 in common years. A rule tied
+ *   to the end of a month (the weekday nearest to, or last in, the month's final days) would
+ *   put a February 28 anchor on February 29 in leap years; this does not — state such a rule
+ *   with a date that exists every year.
  * - Whether a fiscal year has 52 or 53 weeks is derived from the gap between its own two
  *   ends, never assumed from a table.
  * - `value` must be zoneless — an ISO date or datetime, as `isValidIsoDateLike` accepts. See

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

@@ -6,11 +6,7 @@
  * end of a year, so all three fields come back together rather than as three calls a caller
  * could combine inconsistently.
  *
- * - `year` is the ISO week-numbering year (`Temporal.PlainDate.yearOfWeek`), which differs
- *   from the calendar year for late-December and early-January dates.
- * - `week` is 1–53. ISO week 1 is the week containing the year's first Thursday, so a
- *   week-numbering year has 53 weeks roughly every five to six years.
- * - `weekday` is 1 (Monday) through 7 (Sunday).
+ * - A week-numbering year has 53 weeks roughly every five to six years, and 52 otherwise.
  * - `value` must be zoneless — an ISO date or datetime, as `isValidIsoDateLike` accepts. An
  *   offset, a `Z` or a bracketed zone makes it a moment rather than a calendar date; convert
  *   it in the zone you mean first (`convertUtcToZoned` then `convertZonedToPlainDateTime`),
@@ -29,7 +25,16 @@
  * @example getIsoWeekDate("invalid") // null
  */
 export declare function getIsoWeekDate(value: string): {
+    /**
+     * The ISO 8601 week-numbering year: the calendar year that holds the Thursday of the date's week.
+     * It differs from the date's own calendar year for some dates in late December and early January.
+     */
     year: number;
+    /**
+     * The ISO 8601 week number, 1 through 53. Week 1 is the week that holds the year's first
+     * Thursday, and weeks start on Monday.
+     */
     week: number;
+    /** The ISO 8601 day of the week, 1 (Monday) through 7 (Sunday). */
     weekday: number;
 } | null;

package/dist/calendar/calculate/getIsoWeekDate.js

@@ -7,11 +7,7 @@ import { zonelessCalendarDate } from "../../internal/index.js";
  * end of a year, so all three fields come back together rather than as three calls a caller
  * could combine inconsistently.
  *
- * - `year` is the ISO week-numbering year (`Temporal.PlainDate.yearOfWeek`), which differs
- *   from the calendar year for late-December and early-January dates.
- * - `week` is 1–53. ISO week 1 is the week containing the year's first Thursday, so a
- *   week-numbering year has 53 weeks roughly every five to six years.
- * - `weekday` is 1 (Monday) through 7 (Sunday).
+ * - A week-numbering year has 53 weeks roughly every five to six years, and 52 otherwise.
  * - `value` must be zoneless — an ISO date or datetime, as `isValidIsoDateLike` accepts. An
  *   offset, a `Z` or a bracketed zone makes it a moment rather than a calendar date; convert
  *   it in the zone you mean first (`convertUtcToZoned` then `convertZonedToPlainDateTime`),

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

@@ -1,9 +1,8 @@
 /**
  * Return the ISO 8601 ordinal date — calendar year and day of year — for `value`.
  *
- * - `dayOfYear` is 1–365, or 1–366 in a leap year.
- * - `year` is the calendar year, unlike `getIsoWeekDate`'s week-numbering year: an ordinal
- *   date never disagrees with the calendar year it is written beside.
+ * - Unlike `getIsoWeekDate`, whose year is the week-numbering year, an ordinal date never
+ *   disagrees with the calendar year it is written beside.
  * - `value` must be zoneless — an ISO date or datetime, as `isValidIsoDateLike` accepts. See
  *   `getIsoWeekDate` for why a moment is not accepted here.
  * - Returns null on invalid input.
@@ -20,6 +19,14 @@
  * @example getOrdinalDate("invalid") // null
  */
 export declare function getOrdinalDate(value: string): {
+    /**
+     * The calendar year of the date. It is not the ISO 8601 week-numbering year, so it always matches
+     * the year written in `value`.
+     */
     year: number;
+    /**
+     * The 1-based day of that year, the ISO 8601 ordinal day: 1 is January 1, and December 31 is 365,
+     * or 366 in a leap year.
+     */
     dayOfYear: number;
 } | null;

package/dist/calendar/calculate/getOrdinalDate.js

@@ -2,9 +2,8 @@ import { zonelessCalendarDate } from "../../internal/index.js";
 /**
  * Return the ISO 8601 ordinal date — calendar year and day of year — for `value`.
  *
- * - `dayOfYear` is 1–365, or 1–366 in a leap year.
- * - `year` is the calendar year, unlike `getIsoWeekDate`'s week-numbering year: an ordinal
- *   date never disagrees with the calendar year it is written beside.
+ * - Unlike `getIsoWeekDate`, whose year is the week-numbering year, an ordinal date never
+ *   disagrees with the calendar year it is written beside.
  * - `value` must be zoneless — an ISO date or datetime, as `isValidIsoDateLike` accepts. See
  *   `getIsoWeekDate` for why a moment is not accepted here.
  * - Returns null on invalid input.

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

@@ -1,22 +1,19 @@
 /**
  * Return the quarter `value` falls in, as a year and a quarter number.
  *
- * - `quarter` is 1–4. With no options these are the calendar quarters: Q1 is January to
- *   March, and `year` is the calendar year.
- * - `fiscalYearStartMonth` (1–12, default 1) moves the year's first month. A date before it
- *   belongs to the previous fiscal year, so `getQuarter("2024-03-31", { fiscalYearStartMonth:
- *   4 })` is Q4 of 2023.
- * - **`year` is the calendar year the fiscal year starts in**, matching the NRF retail
+ * - With no options these are the calendar quarters: Q1 is January to March, and `year` is
+ *   the calendar year.
+ * - Labelling a fiscal year by the calendar year it starts in matches the NRF retail
  *   convention `getFiscalPeriod` uses. Organisations that label a fiscal year by the calendar
- *   year it *ends* in — the US federal government's October-start FY2025 begins in October
- *   2024 — should add one.
+ *   year it *ends* in — for a fiscal year that starts in October, FY2025 begins in October
+ *   2024 — should add one to `year`.
  * - `value` must be zoneless — an ISO date or datetime, as `isValidIsoDateLike` accepts. See
  *   `getIsoWeekDate` for why a moment is not accepted here.
  * - Returns null on invalid input, including a `fiscalYearStartMonth` that is not an integer
  *   from 1 to 12.
  *
  * @param value zoneless ISO 8601 date or datetime string (e.g. "2024-06-15")
- * @param optionsArg optional: fiscalYearStartMonth (1-12, default 1)
+ * @param optionsArg The month the fiscal year starts in
  * @returns { year, quarter }, or null on invalid input
  *
  * @example getQuarter("2024-06-15") // { year: 2024, quarter: 2 }
@@ -29,8 +26,23 @@
  * @example getQuarter("invalid") // null
  */
 export declare function getQuarter(value: string, optionsArg?: {
+    /**
+     * The month the year starts in, 1 (January) through 12, which makes the quarters fiscal
+     * quarters. A date before it belongs to the previous fiscal year, so with `4` the date
+     * `"2024-03-31"` is Q4 of 2023.
+     *
+     * @defaultValue `1`
+     */
     fiscalYearStartMonth?: number;
 }): {
+    /**
+     * The year the quarter belongs to. With `fiscalYearStartMonth` set, it is the calendar year the
+     * fiscal year starts in, so a date before the start month reports the previous year.
+     */
     year: number;
+    /**
+     * The quarter of that year, 1 through 4. Quarter 1 begins in the `fiscalYearStartMonth` month,
+     * which is January by default.
+     */
     quarter: number;
 } | null;

package/dist/calendar/calculate/getQuarter.js

@@ -1,5 +1,6 @@
 import { zonelessCalendarDate } from "../../internal/index.js";
 import { isOptionsArgument } from "../../internal/isObject.js";
+import { optionOrDefault } from "../../internal/optionOrDefault.js";
 /** Months in a quarter. */
 const MONTHS_PER_QUARTER = 3;
 /** Months in a year. */
@@ -7,22 +8,19 @@ const MONTHS_PER_YEAR = 12;
 /**
  * Return the quarter `value` falls in, as a year and a quarter number.
  *
- * - `quarter` is 1–4. With no options these are the calendar quarters: Q1 is January to
- *   March, and `year` is the calendar year.
- * - `fiscalYearStartMonth` (1–12, default 1) moves the year's first month. A date before it
- *   belongs to the previous fiscal year, so `getQuarter("2024-03-31", { fiscalYearStartMonth:
- *   4 })` is Q4 of 2023.
- * - **`year` is the calendar year the fiscal year starts in**, matching the NRF retail
+ * - With no options these are the calendar quarters: Q1 is January to March, and `year` is
+ *   the calendar year.
+ * - Labelling a fiscal year by the calendar year it starts in matches the NRF retail
  *   convention `getFiscalPeriod` uses. Organisations that label a fiscal year by the calendar
- *   year it *ends* in — the US federal government's October-start FY2025 begins in October
- *   2024 — should add one.
+ *   year it *ends* in — for a fiscal year that starts in October, FY2025 begins in October
+ *   2024 — should add one to `year`.
  * - `value` must be zoneless — an ISO date or datetime, as `isValidIsoDateLike` accepts. See
  *   `getIsoWeekDate` for why a moment is not accepted here.
  * - Returns null on invalid input, including a `fiscalYearStartMonth` that is not an integer
  *   from 1 to 12.
  *
  * @param value zoneless ISO 8601 date or datetime string (e.g. "2024-06-15")
- * @param optionsArg optional: fiscalYearStartMonth (1-12, default 1)
+ * @param optionsArg The month the fiscal year starts in
  * @returns { year, quarter }, or null on invalid input
  *
  * @example getQuarter("2024-06-15") // { year: 2024, quarter: 2 }
@@ -39,9 +37,7 @@ export function getQuarter(value, optionsArg) {
         if (!isOptionsArgument(optionsArg)) {
             return null;
         }
-        const fiscalYearStartMonth = optionsArg?.fiscalYearStartMonth === undefined
-            ? 1
-            : optionsArg.fiscalYearStartMonth;
+        const fiscalYearStartMonth = optionOrDefault(optionsArg?.fiscalYearStartMonth, 1);
         if (!Number.isInteger(fiscalYearStartMonth) ||
             fiscalYearStartMonth < 1 ||
             fiscalYearStartMonth > MONTHS_PER_YEAR) {

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

@@ -0,0 +1,53 @@
+import type { Disambiguation, OperatingSchedule } from "../../types/index.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.
+ *
+ * @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 declare function addOperatingTime(start: string, duration: string, schedule: OperatingSchedule, optionsArg?: {
+    /**
+     * How far after `start` the search may go, as a non-negative ISO 8601 duration added in the
+     * schedule's zone, so `"P1D"` is one local day. A deadline 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 add open time
+     * before the deadline.
+     *
+     * @defaultValue `"compatible"`, Temporal's default.
+     */
+    disambiguation?: Disambiguation;
+}): string;

package/dist/calendar/hours/addOperatingTime.js

@@ -0,0 +1,59 @@
+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.
+ *
+ * @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.timeZone);
+        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,39 @@
+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.
+ *
+ * @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
+ */
+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,44 @@
+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.
+ *
+ * @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
+ */
+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;
+    }
+}