@northguild/gmt 1.17.0 → 1.19.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
@@ -29,11 +29,18 @@ import type { ZoneBucketUnit } from "../../types/index.js";
  *   if a zone ever presented more transitions inside one bucket than the stepper walks — no
  *   IANA zone does, and the whole table was swept to confirm it. A truncated list would be
  *   worse than the sentinel, so none is returned in any of those cases.
+ * - **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 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 unit bucket unit ("month" | "week" | "day" | "hour", or its plural)
+ * @param timeZone IANA name or UTC offset the buckets are computed in: a time zone identifier
+ *   (`+05:30`, `+0530`, `-08`) or a stored offset (`±HH:MM[:SS]`, what `getTimeZoneOffset` returns)
  * @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"]
@@ -45,5 +52,6 @@ import type { ZoneBucketUnit } from "../../types/index.js";
  * @example bucketRange("2024-06-16T00:00:00Z", "2024-06-15T00:00:00Z", "day", "UTC") // [] (start after end)
  * @example bucketRange("2024-06-15T03:00:00Z", "2024-06-17T03:00:00Z", "days", "America/New_York") // ["2024-06-14T04:00:00Z", "2024-06-15T04:00:00Z", "2024-06-16T04:00:00Z"] (plural unit name)
  * @example bucketRange("2024-06-15T03:00:00Z", "2024-06-17T03:00:00Z", "year", "UTC") // [] (not a bucketing unit)
+ * @example bucketRange("1970-01-01T00:00:00Z", "1970-01-02T01:00:00Z", "day", "-00:44:30") // ["1969-12-31T00:44:30Z", "1970-01-01T00:44:30Z", "1970-01-02T00:44:30Z"]
  */
 export declare function bucketRange(start: string, end: string, unit: Temporal.SmallestUnit<ZoneBucketUnit>, timeZone: string): string[];

package/dist/calendar/calculate/bucketRange.js

@@ -1,9 +1,9 @@
 import { Temporal } from "@js-temporal/polyfill";
-import { nextZonedBucketStart, zonedNextTransition, zonedUnitStart, } from "../../internal/index.js";
+import { frameInstant, frameZoned, instantFrom, nextZonedBucketStart, zonedUnitStart, zoneFrame, } from "../../internal/index.js";
 import { isValidInstant } from "../../precision/validate/index.js";
-import { isValidTimeZone } from "../../zoned/validate/index.js";
 import { isValidZoneBucketUnit } from "../validate/index.js";
 import { resolveDateTimeUnit } from "../../internal/resolveDateTimeUnit.js";
+import { certainlyTouchesMoreBuckets } from "../../internal/zoneBucketCap.js";
 /**
  * Buckets a single call will return before giving up.
  *
@@ -12,58 +12,6 @@ import { resolveDateTimeUnit } from "../../internal/resolveDateTimeUnit.js";
  * months — past anything a caller renders or aggregates in one pass.
  */
 const MAX_BUCKETS = 10_000;
-const NANOSECONDS_PER_HOUR = 3600000000000n;
-/**
- * The longest wall-clock stretch of each unit. Any wall-clock interval this long holds a unit
- * start: an hour holds an hour start, 24 hours a midnight, 7 days a Monday, 31 days a first of
- * the month.
- */
-const LONGEST_UNIT_NANOSECONDS = {
-    hour: NANOSECONDS_PER_HOUR,
-    day: 24n * NANOSECONDS_PER_HOUR,
-    week: 168n * NANOSECONDS_PER_HOUR,
-    month: 744n * NANOSECONDS_PER_HOUR,
-};
-/** Offset transitions read before the pre-count gives up and leaves the answer to the walk. */
-const MAX_PRECOUNT_TRANSITIONS = 4_096;
-/**
- * True when `[start, end)` certainly touches more than `MAX_BUCKETS` buckets, decided from the span
- * instead of stepping bucket by bucket (which costs milliseconds a step in some zones).
- *
- * Over a prefix of the range, the local wall clock runs continuously between offset transitions.
- * Those stretches cover at least the prefix's length less every backward offset change, in at most
- * one stretch more than there are transitions, and each stretch of wall clock holds at least
- * `floor(length / LONGEST_UNIT_NANOSECONDS)` distinct unit starts, each the start of its own
- * bucket before `end`. The count subtracts two per stretch for the partial units at its ends.
- * `false` means "not certain": the walk decides, exactly as before.
- */
-function certainlyExceedsBucketCap(startZoned, endZoned, unit) {
-    const unitNs = LONGEST_UNIT_NANOSECONDS[unit];
-    const startNs = startZoned.epochNanoseconds;
-    const prefixEndNs = [
-        endZoned.epochNanoseconds,
-        startNs + 2n * BigInt(MAX_BUCKETS + 1) * unitNs,
-    ].reduce((a, b) => (a < b ? a : b));
-    if (prefixEndNs - startNs <= BigInt(MAX_BUCKETS) * unitNs) {
-        return false;
-    }
-    let backwardNs = 0n;
-    let transitions = 0;
-    try {
-        for (let current = startZoned, next = zonedNextTransition(current); next !== null && next.epochNanoseconds < prefixEndNs; current = next, next = zonedNextTransition(current)) {
-            if (++transitions > MAX_PRECOUNT_TRANSITIONS) {
-                return false;
-            }
-            const shift = BigInt(current.offsetNanoseconds - next.offsetNanoseconds);
-            backwardNs += shift > 0n ? shift : 0n;
-        }
-    }
-    catch {
-        return false;
-    }
-    const wallStarts = (prefixEndNs - startNs - backwardNs) / unitNs;
-    return wallStarts - 2n * BigInt(transitions + 1) > BigInt(MAX_BUCKETS);
-}
 /**
  * The bucket start after `current`: `undefined` when it lies past Temporal's last representable
  * instant, null when the stepper cannot find it.
@@ -93,8 +41,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
@@ -107,11 +55,18 @@ function nextBucketStartWithinRange(current, unit) {
  *   if a zone ever presented more transitions inside one bucket than the stepper walks — no
  *   IANA zone does, and the whole table was swept to confirm it. A truncated list would be
  *   worse than the sentinel, so none is returned in any of those cases.
+ * - **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 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 unit bucket unit ("month" | "week" | "day" | "hour", or its plural)
+ * @param timeZone IANA name or UTC offset the buckets are computed in: a time zone identifier
+ *   (`+05:30`, `+0530`, `-08`) or a stored offset (`±HH:MM[:SS]`, what `getTimeZoneOffset` returns)
  * @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"]
@@ -123,22 +78,24 @@ function nextBucketStartWithinRange(current, unit) {
  * @example bucketRange("2024-06-16T00:00:00Z", "2024-06-15T00:00:00Z", "day", "UTC") // [] (start after end)
  * @example bucketRange("2024-06-15T03:00:00Z", "2024-06-17T03:00:00Z", "days", "America/New_York") // ["2024-06-14T04:00:00Z", "2024-06-15T04:00:00Z", "2024-06-16T04:00:00Z"] (plural unit name)
  * @example bucketRange("2024-06-15T03:00:00Z", "2024-06-17T03:00:00Z", "year", "UTC") // [] (not a bucketing unit)
+ * @example bucketRange("1970-01-01T00:00:00Z", "1970-01-02T01:00:00Z", "day", "-00:44:30") // ["1969-12-31T00:44:30Z", "1970-01-01T00:44:30Z", "1970-01-02T00:44:30Z"]
  */
 export function bucketRange(start, end, unit, timeZone) {
     // The singular name; the guard below rejects anything outside the four units.
     const resolvedUnit = resolveDateTimeUnit(unit);
+    const frame = zoneFrame(timeZone);
     if (!isValidInstant(start) ||
         !isValidInstant(end) ||
         !isValidZoneBucketUnit(resolvedUnit) ||
-        !isValidTimeZone(timeZone)) {
+        frame === null) {
         return [];
     }
     try {
-        const startZoned = Temporal.Instant.from(start).toZonedDateTimeISO(timeZone);
-        const endZoned = Temporal.Instant.from(end).toZonedDateTimeISO(timeZone);
+        const startZoned = frameZoned(instantFrom(start), frame);
+        const endZoned = frameZoned(instantFrom(end), frame);
         if (Temporal.ZonedDateTime.compare(startZoned, endZoned) > 0)
             return [];
-        if (certainlyExceedsBucketCap(startZoned, endZoned, resolvedUnit))
+        if (certainlyTouchesMoreBuckets(startZoned, endZoned, resolvedUnit, MAX_BUCKETS))
             return [];
         const boundaries = [];
         const first = zonedUnitStart(startZoned, resolvedUnit);
@@ -149,7 +106,7 @@ export function bucketRange(start, end, unit, timeZone) {
             if (Temporal.ZonedDateTime.compare(current, endZoned) >= 0) {
                 return boundaries;
             }
-            boundaries.push(current.toInstant().toString());
+            boundaries.push(frameInstant(current, frame).toString());
             const next = nextBucketStartWithinRange(current, resolvedUnit);
             // Past the last representable instant, so after `end`: every touched bucket is collected.
             if (next === undefined)

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,17 +15,26 @@ 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.
  * - Returns a UTC instant string ending in `"Z"`, exactly — no rounding.
  * - Returns `""` on invalid input, and where the boundary itself is not representable — the
  *   week or month containing the first instant Temporal supports began before it.
+ * - **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 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 unit boundary unit ("month" | "week" | "day" | "hour", or its plural)
+ * @param timeZone IANA name or UTC offset the boundary is computed in: a time zone identifier
+ *   (`+05:30`, `+0530`, `-08`) or a stored offset (`±HH:MM[:SS]`, what `getTimeZoneOffset` returns)
  * @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)
@@ -38,5 +47,6 @@ import type { ZoneBucketUnit } from "../../types/index.js";
  * @example floorToZone("2024-06-15T03:00:00", "day", "UTC") // "" (zoneless, so it names no instant)
  * @example floorToZone("-271821-04-20T00:00:00Z", "month", "UTC") // "" (that month began before Temporal's range does)
  * @example floorToZone("2024-06-15T03:00:00Z", "day", "Invalid/Zone") // ""
+ * @example floorToZone("1970-01-01T13:00:00Z", "day", "-00:44:30") // "1970-01-01T00:44:30Z" (local midnight at a stored offset with seconds)
  */
 export declare function floorToZone(value: string, unit: Temporal.SmallestUnit<ZoneBucketUnit>, timeZone: string): string;

package/dist/calendar/calculate/floorToZone.js

@@ -1,7 +1,5 @@
-import { Temporal } from "@js-temporal/polyfill";
-import { zonedUnitStart } from "../../internal/index.js";
+import { frameInstant, frameZoned, instantFrom, zonedUnitStart, zoneFrame, } from "../../internal/index.js";
 import { isValidInstant } from "../../precision/validate/index.js";
-import { isValidTimeZone } from "../../zoned/validate/index.js";
 import { isValidZoneBucketUnit } from "../validate/index.js";
 import { resolveDateTimeUnit } from "../../internal/resolveDateTimeUnit.js";
 /**
@@ -19,17 +17,26 @@ 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.
  * - Returns a UTC instant string ending in `"Z"`, exactly — no rounding.
  * - Returns `""` on invalid input, and where the boundary itself is not representable — the
  *   week or month containing the first instant Temporal supports began before it.
+ * - **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 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 unit boundary unit ("month" | "week" | "day" | "hour", or its plural)
+ * @param timeZone IANA name or UTC offset the boundary is computed in: a time zone identifier
+ *   (`+05:30`, `+0530`, `-08`) or a stored offset (`±HH:MM[:SS]`, what `getTimeZoneOffset` returns)
  * @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)
@@ -42,19 +49,21 @@ import { resolveDateTimeUnit } from "../../internal/resolveDateTimeUnit.js";
  * @example floorToZone("2024-06-15T03:00:00", "day", "UTC") // "" (zoneless, so it names no instant)
  * @example floorToZone("-271821-04-20T00:00:00Z", "month", "UTC") // "" (that month began before Temporal's range does)
  * @example floorToZone("2024-06-15T03:00:00Z", "day", "Invalid/Zone") // ""
+ * @example floorToZone("1970-01-01T13:00:00Z", "day", "-00:44:30") // "1970-01-01T00:44:30Z" (local midnight at a stored offset with seconds)
  */
 export function floorToZone(value, unit, timeZone) {
     // The singular name; the guard below rejects anything outside the four units.
     const resolvedUnit = resolveDateTimeUnit(unit);
+    const frame = zoneFrame(timeZone);
     if (!isValidInstant(value) ||
         !isValidZoneBucketUnit(resolvedUnit) ||
-        !isValidTimeZone(timeZone)) {
+        frame === null) {
         return "";
     }
     try {
-        const zoned = Temporal.Instant.from(value).toZonedDateTimeISO(timeZone);
+        const zoned = frameZoned(instantFrom(value), frame);
         const start = zonedUnitStart(zoned, resolvedUnit);
-        return start ? start.toInstant().toString() : "";
+        return start ? frameInstant(start, frame).toString() : "";
     }
     catch {
         return "";

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,59 @@
+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.
+ * - **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 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;