@northguild/gmt 1.18.0 → 1.20.0

package/dist/calendar/business/businessDaysBetween.d.ts

@@ -24,11 +24,11 @@ import type { BusinessCalendar } from "../../types/index.js";
  * @param calendar BusinessCalendar naming the weekend days and holidays
  * @returns number of working days in `(start, end]`, negative when `end` precedes `start`, or null on invalid input
  *
- * @example businessDaysBetween("2024-07-01", "2024-07-05", { weekend: [6, 7], holidays: ["2024-07-04"], timeZone: "America/New_York" }) // 3 — Tue, Wed, Fri
+ * @example businessDaysBetween("2024-07-01", "2024-07-05", { weekend: [6, 7], holidays: ["2024-07-04"], timeZone: "Africa/Kigali" }) // 3 — Tue, Wed, Fri
  * @example businessDaysBetween("2024-07-05", "2024-07-08", { weekend: [6, 7], holidays: [], timeZone: "UTC" }) // 1 — Monday, over the weekend
  * @example businessDaysBetween("2024-07-01", "2024-07-31", { weekend: [6, 7], holidays: [], timeZone: "UTC" }) // 22 — July's 23 weekdays less the 1st
  * @example businessDaysBetween("2024-07-01", "2024-07-01", { weekend: [6, 7], holidays: [], timeZone: "UTC" }) // 0
- * @example businessDaysBetween("2024-07-05", "2024-07-01", { weekend: [6, 7], holidays: ["2024-07-04"], timeZone: "America/New_York" }) // -3 — reversed
+ * @example businessDaysBetween("2024-07-05", "2024-07-01", { weekend: [6, 7], holidays: ["2024-07-04"], timeZone: "Africa/Kigali" }) // -3 — reversed
  * @example businessDaysBetween("2024-07-06", "2024-07-05", { weekend: [6, 7], holidays: [], timeZone: "UTC" }) // 0 — addBusinessDays("2024-07-06", -1) is "2024-07-05", but Saturday is excluded
  * @example businessDaysBetween("2024-07-01", "2024-07-08", { weekend: [5, 6], holidays: [], timeZone: "Asia/Riyadh" }) // 5 — Friday–Saturday weekend
  * @example businessDaysBetween("invalid", "2024-07-05", { weekend: [6, 7], holidays: [], timeZone: "UTC" }) // null

package/dist/calendar/business/businessDaysBetween.js

@@ -1,33 +1,7 @@
-import { Temporal } from "@js-temporal/polyfill";
-import { parseBusinessCalendar } from "../../internal/businessCalendar.js";
+import { Temporal } from "../../internal/temporal.js";
+import { businessDaysWithin, parseBusinessCalendar, } from "../../internal/businessCalendar.js";
+import { epochDayOfDate } from "../../internal/epochDay.js";
 import { isValidDate } from "../../plain/validate/index.js";
-const DAYS_PER_WEEK = 7;
-/**
- * Count the business days in `(from, to]`, given `from` is not after `to`.
- *
- * Whole weeks contribute one of each weekday, so only the remainder is walked and the count
- * costs the same for a range of days as for one of centuries.
- */
-function countBusinessDates(from, to, weekend, holidays) {
-    const days = from.until(to, { largestUnit: "day" }).days;
-    const wholeWeeks = Math.floor(days / DAYS_PER_WEEK);
-    const businessDaysPerWeek = DAYS_PER_WEEK - weekend.size;
-    let count = wholeWeeks * businessDaysPerWeek;
-    for (let offset = wholeWeeks * DAYS_PER_WEEK + 1; offset <= days; offset++) {
-        if (!weekend.has(from.add({ days: offset }).dayOfWeek)) {
-            count += 1;
-        }
-    }
-    for (const holiday of holidays) {
-        const date = Temporal.PlainDate.from(holiday);
-        const insideRange = Temporal.PlainDate.compare(date, from) > 0 &&
-            Temporal.PlainDate.compare(date, to) <= 0;
-        if (insideRange && !weekend.has(date.dayOfWeek)) {
-            count -= 1;
-        }
-    }
-    return count;
-}
 /**
  * Count the working days between two local dates, **excluding `start` and including `end`**.
  *
@@ -53,11 +27,11 @@ function countBusinessDates(from, to, weekend, holidays) {
  * @param calendar BusinessCalendar naming the weekend days and holidays
  * @returns number of working days in `(start, end]`, negative when `end` precedes `start`, or null on invalid input
  *
- * @example businessDaysBetween("2024-07-01", "2024-07-05", { weekend: [6, 7], holidays: ["2024-07-04"], timeZone: "America/New_York" }) // 3 — Tue, Wed, Fri
+ * @example businessDaysBetween("2024-07-01", "2024-07-05", { weekend: [6, 7], holidays: ["2024-07-04"], timeZone: "Africa/Kigali" }) // 3 — Tue, Wed, Fri
  * @example businessDaysBetween("2024-07-05", "2024-07-08", { weekend: [6, 7], holidays: [], timeZone: "UTC" }) // 1 — Monday, over the weekend
  * @example businessDaysBetween("2024-07-01", "2024-07-31", { weekend: [6, 7], holidays: [], timeZone: "UTC" }) // 22 — July's 23 weekdays less the 1st
  * @example businessDaysBetween("2024-07-01", "2024-07-01", { weekend: [6, 7], holidays: [], timeZone: "UTC" }) // 0
- * @example businessDaysBetween("2024-07-05", "2024-07-01", { weekend: [6, 7], holidays: ["2024-07-04"], timeZone: "America/New_York" }) // -3 — reversed
+ * @example businessDaysBetween("2024-07-05", "2024-07-01", { weekend: [6, 7], holidays: ["2024-07-04"], timeZone: "Africa/Kigali" }) // -3 — reversed
  * @example businessDaysBetween("2024-07-06", "2024-07-05", { weekend: [6, 7], holidays: [], timeZone: "UTC" }) // 0 — addBusinessDays("2024-07-06", -1) is "2024-07-05", but Saturday is excluded
  * @example businessDaysBetween("2024-07-01", "2024-07-08", { weekend: [5, 6], holidays: [], timeZone: "Asia/Riyadh" }) // 5 — Friday–Saturday weekend
  * @example businessDaysBetween("invalid", "2024-07-05", { weekend: [6, 7], holidays: [], timeZone: "UTC" }) // null
@@ -70,10 +44,12 @@ export function businessDaysBetween(start, end, calendar) {
             return null;
         }
         try {
-            const startDate = Temporal.PlainDate.from(start);
-            const endDate = Temporal.PlainDate.from(end);
-            const reversed = Temporal.PlainDate.compare(startDate, endDate) > 0;
-            const count = countBusinessDates(reversed ? endDate : startDate, reversed ? startDate : endDate, resolved.weekend, resolved.holidays);
+            const startDay = epochDayOfDate(Temporal.PlainDate.from(start));
+            const endDay = epochDayOfDate(Temporal.PlainDate.from(end));
+            const reversed = startDay > endDay;
+            const count = reversed
+                ? businessDaysWithin(endDay + 1, startDay, resolved)
+                : businessDaysWithin(startDay + 1, endDay, resolved);
             // `0 - count` rather than `-count`: an empty reversed range must be 0, not -0.
             return reversed ? 0 - count : count;
         }

package/dist/calendar/business/mergeCalendars.d.ts

@@ -23,7 +23,7 @@ import type { BusinessCalendar } from "../../types/index.js";
  * @param calendars array of BusinessCalendar records to compose
  * @returns merged BusinessCalendar, or null on invalid input
  *
- * @example mergeCalendars([{ weekend: [6, 7], holidays: ["2024-07-04"], timeZone: "America/New_York" }, { weekend: [6, 7], holidays: ["2024-05-06"], timeZone: "Europe/London" }]) // { weekend: [6, 7], holidays: ["2024-05-06", "2024-07-04"], timeZone: "America/New_York" }
+ * @example mergeCalendars([{ weekend: [6, 7], holidays: ["2024-07-04"], timeZone: "Africa/Kigali" }, { weekend: [6, 7], holidays: ["2024-05-06"], timeZone: "Europe/London" }]) // { weekend: [6, 7], holidays: ["2024-05-06", "2024-07-04"], timeZone: "Africa/Kigali" }
  * @example mergeCalendars([{ weekend: [6, 7], holidays: [], timeZone: "UTC" }, { weekend: [5, 6], holidays: [], timeZone: "Asia/Riyadh" }]) // { weekend: [5, 6, 7], holidays: [], timeZone: "UTC" } — only Sunday to Thursday survive
  * @example mergeCalendars([{ weekend: [6, 7], holidays: ["2024-07-04"], timeZone: "UTC" }]) // { weekend: [6, 7], holidays: ["2024-07-04"], timeZone: "UTC" }
  * @example mergeCalendars([]) // null

package/dist/calendar/business/mergeCalendars.js

@@ -1,5 +1,5 @@
-import { Temporal } from "@js-temporal/polyfill";
 import { parseBusinessCalendar } from "../../internal/businessCalendar.js";
+import { isoDateString, sortedUnique } from "../../internal/epochDay.js";
 /**
  * Compose several jurisdictions' calendars into one whose working days are those they all
  * share.
@@ -24,7 +24,7 @@ import { parseBusinessCalendar } from "../../internal/businessCalendar.js";
  * @param calendars array of BusinessCalendar records to compose
  * @returns merged BusinessCalendar, or null on invalid input
  *
- * @example mergeCalendars([{ weekend: [6, 7], holidays: ["2024-07-04"], timeZone: "America/New_York" }, { weekend: [6, 7], holidays: ["2024-05-06"], timeZone: "Europe/London" }]) // { weekend: [6, 7], holidays: ["2024-05-06", "2024-07-04"], timeZone: "America/New_York" }
+ * @example mergeCalendars([{ weekend: [6, 7], holidays: ["2024-07-04"], timeZone: "Africa/Kigali" }, { weekend: [6, 7], holidays: ["2024-05-06"], timeZone: "Europe/London" }]) // { weekend: [6, 7], holidays: ["2024-05-06", "2024-07-04"], timeZone: "Africa/Kigali" }
  * @example mergeCalendars([{ weekend: [6, 7], holidays: [], timeZone: "UTC" }, { weekend: [5, 6], holidays: [], timeZone: "Asia/Riyadh" }]) // { weekend: [5, 6, 7], holidays: [], timeZone: "UTC" } — only Sunday to Thursday survive
  * @example mergeCalendars([{ weekend: [6, 7], holidays: ["2024-07-04"], timeZone: "UTC" }]) // { weekend: [6, 7], holidays: ["2024-07-04"], timeZone: "UTC" }
  * @example mergeCalendars([]) // null
@@ -37,7 +37,7 @@ export function mergeCalendars(calendars) {
             return null;
         }
         const weekend = new Set();
-        const holidays = new Set();
+        const holidayLists = [];
         for (const calendar of calendars) {
             const resolved = parseBusinessCalendar(calendar);
             if (resolved === null) {
@@ -46,15 +46,14 @@ export function mergeCalendars(calendars) {
             for (const day of resolved.weekend) {
                 weekend.add(day);
             }
-            for (const holiday of resolved.holidays) {
-                holidays.add(holiday);
-            }
+            holidayLists.push(resolved.holidays);
         }
+        const holidays = sortedUnique(Int32Array.from(holidayLists.flatMap((list) => Array.from(list))));
         const merged = {
             weekend: [...weekend].sort((a, b) => a - b),
-            // Chronological, not lexicographic: a bare `.sort()` compares as strings, which puts the
-            // "+" and "-" of an expanded year below every digit.
-            holidays: [...holidays].sort((a, b) => Temporal.PlainDate.compare(a, b)),
+            // Epoch days sort chronologically, which a string sort would not: it puts the "+" and "-"
+            // of an expanded year below every digit.
+            holidays: Array.from(holidays, (day) => isoDateString(day)),
             timeZone: calendars[0].timeZone,
         };
         // The union can close every weekday even when no input does, which is not a calendar.

package/dist/calendar/business/nextBusinessDay.d.ts

@@ -20,8 +20,8 @@ import type { BusinessCalendar } from "../../types/index.js";
  * @param calendar BusinessCalendar naming the weekend days and holidays
  * @returns ISO PlainDate string of the next working day, or "" on invalid input
  *
- * @example nextBusinessDay("2024-07-03", { weekend: [6, 7], holidays: ["2024-07-04"], timeZone: "America/New_York" }) // "2024-07-05" — skips the holiday
- * @example nextBusinessDay("2024-07-04", { weekend: [6, 7], holidays: ["2024-07-04"], timeZone: "America/New_York" }) // "2024-07-05" — from the holiday itself
+ * @example nextBusinessDay("2024-07-03", { weekend: [6, 7], holidays: ["2024-07-04"], timeZone: "Africa/Kigali" }) // "2024-07-05" — skips the holiday
+ * @example nextBusinessDay("2024-07-04", { weekend: [6, 7], holidays: ["2024-07-04"], timeZone: "Africa/Kigali" }) // "2024-07-05" — from the holiday itself
  * @example nextBusinessDay("2024-07-05", { weekend: [6, 7], holidays: [], timeZone: "UTC" }) // "2024-07-08" — Friday over the weekend
  * @example nextBusinessDay("2024-07-04", { weekend: [5, 6], holidays: [], timeZone: "Asia/Riyadh" }) // "2024-07-07" — Friday–Saturday weekend
  * @example nextBusinessDay("invalid", { weekend: [6, 7], holidays: [], timeZone: "UTC" }) // ""

package/dist/calendar/business/nextBusinessDay.js

@@ -20,8 +20,8 @@ import { neighbourBusinessDayValue } from "../../internal/businessDayValues.js";
  * @param calendar BusinessCalendar naming the weekend days and holidays
  * @returns ISO PlainDate string of the next working day, or "" on invalid input
  *
- * @example nextBusinessDay("2024-07-03", { weekend: [6, 7], holidays: ["2024-07-04"], timeZone: "America/New_York" }) // "2024-07-05" — skips the holiday
- * @example nextBusinessDay("2024-07-04", { weekend: [6, 7], holidays: ["2024-07-04"], timeZone: "America/New_York" }) // "2024-07-05" — from the holiday itself
+ * @example nextBusinessDay("2024-07-03", { weekend: [6, 7], holidays: ["2024-07-04"], timeZone: "Africa/Kigali" }) // "2024-07-05" — skips the holiday
+ * @example nextBusinessDay("2024-07-04", { weekend: [6, 7], holidays: ["2024-07-04"], timeZone: "Africa/Kigali" }) // "2024-07-05" — from the holiday itself
  * @example nextBusinessDay("2024-07-05", { weekend: [6, 7], holidays: [], timeZone: "UTC" }) // "2024-07-08" — Friday over the weekend
  * @example nextBusinessDay("2024-07-04", { weekend: [5, 6], holidays: [], timeZone: "Asia/Riyadh" }) // "2024-07-07" — Friday–Saturday weekend
  * @example nextBusinessDay("invalid", { weekend: [6, 7], holidays: [], timeZone: "UTC" }) // ""

package/dist/calendar/business/previousBusinessDay.d.ts

@@ -20,8 +20,8 @@ import type { BusinessCalendar } from "../../types/index.js";
  * @param calendar BusinessCalendar naming the weekend days and holidays
  * @returns ISO PlainDate string of the previous working day, or "" on invalid input
  *
- * @example previousBusinessDay("2024-07-05", { weekend: [6, 7], holidays: ["2024-07-04"], timeZone: "America/New_York" }) // "2024-07-03" — skips the holiday
- * @example previousBusinessDay("2024-07-04", { weekend: [6, 7], holidays: ["2024-07-04"], timeZone: "America/New_York" }) // "2024-07-03" — from the holiday itself
+ * @example previousBusinessDay("2024-07-05", { weekend: [6, 7], holidays: ["2024-07-04"], timeZone: "Africa/Kigali" }) // "2024-07-03" — skips the holiday
+ * @example previousBusinessDay("2024-07-04", { weekend: [6, 7], holidays: ["2024-07-04"], timeZone: "Africa/Kigali" }) // "2024-07-03" — from the holiday itself
  * @example previousBusinessDay("2024-07-08", { weekend: [6, 7], holidays: [], timeZone: "UTC" }) // "2024-07-05" — Monday back over the weekend
  * @example previousBusinessDay("2024-07-07", { weekend: [5, 6], holidays: [], timeZone: "Asia/Riyadh" }) // "2024-07-04" — Friday–Saturday weekend
  * @example previousBusinessDay("invalid", { weekend: [6, 7], holidays: [], timeZone: "UTC" }) // ""

package/dist/calendar/business/previousBusinessDay.js

@@ -20,8 +20,8 @@ import { neighbourBusinessDayValue } from "../../internal/businessDayValues.js";
  * @param calendar BusinessCalendar naming the weekend days and holidays
  * @returns ISO PlainDate string of the previous working day, or "" on invalid input
  *
- * @example previousBusinessDay("2024-07-05", { weekend: [6, 7], holidays: ["2024-07-04"], timeZone: "America/New_York" }) // "2024-07-03" — skips the holiday
- * @example previousBusinessDay("2024-07-04", { weekend: [6, 7], holidays: ["2024-07-04"], timeZone: "America/New_York" }) // "2024-07-03" — from the holiday itself
+ * @example previousBusinessDay("2024-07-05", { weekend: [6, 7], holidays: ["2024-07-04"], timeZone: "Africa/Kigali" }) // "2024-07-03" — skips the holiday
+ * @example previousBusinessDay("2024-07-04", { weekend: [6, 7], holidays: ["2024-07-04"], timeZone: "Africa/Kigali" }) // "2024-07-03" — from the holiday itself
  * @example previousBusinessDay("2024-07-08", { weekend: [6, 7], holidays: [], timeZone: "UTC" }) // "2024-07-05" — Monday back over the weekend
  * @example previousBusinessDay("2024-07-07", { weekend: [5, 6], holidays: [], timeZone: "Asia/Riyadh" }) // "2024-07-04" — Friday–Saturday weekend
  * @example previousBusinessDay("invalid", { weekend: [6, 7], holidays: [], timeZone: "UTC" }) // ""

package/dist/calendar/business/rollDate.d.ts

@@ -46,9 +46,9 @@ import type { BusinessCalendar, RollConvention } from "../../types/index.js";
  * @param calendar BusinessCalendar naming the weekend days and holidays
  * @returns ISO PlainDate string of the rolled date, or "" on invalid input
  *
- * @example rollDate("2024-05-31", "following", { weekend: [6, 7], holidays: ["2024-05-31"], timeZone: "America/New_York" }) // "2024-06-03"
- * @example rollDate("2024-05-31", "modifiedFollowing", { weekend: [6, 7], holidays: ["2024-05-31"], timeZone: "America/New_York" }) // "2024-05-30" — forward would leave May
- * @example rollDate("2024-06-01", "modifiedPreceding", { weekend: [6, 7], holidays: ["2024-05-31"], timeZone: "America/New_York" }) // "2024-06-03" — backward would leave June
+ * @example rollDate("2024-05-31", "following", { weekend: [6, 7], holidays: ["2024-05-31"], timeZone: "Europe/London" }) // "2024-06-03"
+ * @example rollDate("2024-05-31", "modifiedFollowing", { weekend: [6, 7], holidays: ["2024-05-31"], timeZone: "Europe/London" }) // "2024-05-30" — forward would leave May
+ * @example rollDate("2024-06-01", "modifiedPreceding", { weekend: [6, 7], holidays: ["2024-05-31"], timeZone: "Europe/London" }) // "2024-06-03" — backward would leave June
  * @example rollDate("2024-05-29", "following", { weekend: [6, 7], holidays: [], timeZone: "UTC" }) // "2024-05-29" — already a working day
  * @example rollDate("2024-03-15", "endOfMonth", { weekend: [6, 7], holidays: [], timeZone: "UTC" }) // "2024-03-29" — March ends on a Sunday
  * @example rollDate("2024-06-01", "none", { weekend: [6, 7], holidays: [], timeZone: "UTC" }) // "2024-06-01" — a Saturday, unadjusted

package/dist/calendar/business/rollDate.js

@@ -1,40 +1,7 @@
-import { Temporal } from "@js-temporal/polyfill";
-import { businessDateFrom, parseBusinessCalendar, } from "../../internal/businessCalendar.js";
-import { isValidDate } from "../../plain/validate/index.js";
-import { isValidRollConvention } from "../validate/index.js";
-function sameMonth(a, b) {
-    return a.year === b.year && a.month === b.month;
-}
-/**
- * Roll in `direction`, and if that leaves the date's month, roll the other way instead.
- */
-function modifiedRoll(date, direction, calendar) {
-    const rolled = businessDateFrom(date, direction, calendar);
-    // An exhausted walk is a sentinel, not a "left the month" answer: turning round here would
-    // report the opposite direction's date as though the first walk had succeeded.
-    if (rolled === null) {
-        return null;
-    }
-    return sameMonth(rolled, date)
-        ? rolled
-        : businessDateFrom(date, direction === 1 ? -1 : 1, calendar);
-}
-function rollTo(date, convention, calendar) {
-    switch (convention) {
-        case "following":
-            return businessDateFrom(date, 1, calendar);
-        case "preceding":
-            return businessDateFrom(date, -1, calendar);
-        case "modifiedFollowing":
-            return modifiedRoll(date, 1, calendar);
-        case "modifiedPreceding":
-            return modifiedRoll(date, -1, calendar);
-        case "endOfMonth":
-            return businessDateFrom(date.with({ day: date.daysInMonth }), -1, calendar);
-        case "none":
-            return date;
-    }
-}
+import { Temporal } from "../../internal/temporal.js";
+import { parseBusinessCalendar } from "../../internal/businessCalendar.js";
+import { rollBusinessDate } from "../../internal/rollBusinessDate.js";
+import { isDateString, isRollConventionName } from "../../internal/inputChecks.js";
 /**
  * Move a local date onto a working day according to `convention`.
  *
@@ -82,9 +49,9 @@ function rollTo(date, convention, calendar) {
  * @param calendar BusinessCalendar naming the weekend days and holidays
  * @returns ISO PlainDate string of the rolled date, or "" on invalid input
  *
- * @example rollDate("2024-05-31", "following", { weekend: [6, 7], holidays: ["2024-05-31"], timeZone: "America/New_York" }) // "2024-06-03"
- * @example rollDate("2024-05-31", "modifiedFollowing", { weekend: [6, 7], holidays: ["2024-05-31"], timeZone: "America/New_York" }) // "2024-05-30" — forward would leave May
- * @example rollDate("2024-06-01", "modifiedPreceding", { weekend: [6, 7], holidays: ["2024-05-31"], timeZone: "America/New_York" }) // "2024-06-03" — backward would leave June
+ * @example rollDate("2024-05-31", "following", { weekend: [6, 7], holidays: ["2024-05-31"], timeZone: "Europe/London" }) // "2024-06-03"
+ * @example rollDate("2024-05-31", "modifiedFollowing", { weekend: [6, 7], holidays: ["2024-05-31"], timeZone: "Europe/London" }) // "2024-05-30" — forward would leave May
+ * @example rollDate("2024-06-01", "modifiedPreceding", { weekend: [6, 7], holidays: ["2024-05-31"], timeZone: "Europe/London" }) // "2024-06-03" — backward would leave June
  * @example rollDate("2024-05-29", "following", { weekend: [6, 7], holidays: [], timeZone: "UTC" }) // "2024-05-29" — already a working day
  * @example rollDate("2024-03-15", "endOfMonth", { weekend: [6, 7], holidays: [], timeZone: "UTC" }) // "2024-03-29" — March ends on a Sunday
  * @example rollDate("2024-06-01", "none", { weekend: [6, 7], holidays: [], timeZone: "UTC" }) // "2024-06-01" — a Saturday, unadjusted
@@ -95,13 +62,13 @@ function rollTo(date, convention, calendar) {
 export function rollDate(value, convention, calendar) {
     try {
         const resolved = parseBusinessCalendar(calendar);
-        if (!isValidDate(value) ||
-            !isValidRollConvention(convention) ||
+        if (!isDateString(value) ||
+            !isRollConventionName(convention) ||
             resolved === null) {
             return "";
         }
         try {
-            const rolled = rollTo(Temporal.PlainDate.from(value), convention, resolved);
+            const rolled = rollBusinessDate(Temporal.PlainDate.from(value), convention, resolved);
             return rolled === null ? "" : rolled.toString();
         }
         catch {

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

@@ -1,10 +1,10 @@
-import { Temporal } from "@js-temporal/polyfill";
+import { Temporal } from "../../internal/temporal.js";
 import type { ZoneBucketUnit } from "../../types/index.js";
 /**
  * Return the start instant of every `unit` bucket the half-open range `[start, end)` touches,
  * bucketed **in `timeZone`**.
  *
- * This is "group by day in `America/New_York`" over UTC timestamps, done correctly. Buckets
+ * This is "group by day in `Europe/London`" over UTC timestamps, done correctly. Buckets
  * are not uniform in length and that is the point: a day that springs forward is 23 hours and
  * one that falls back is 25, so a daily aggregate built on a fixed 24 hours drifts an hour
  * twice a year, and a container's chargeable days — counted in terminal-local calendar days —
@@ -29,21 +29,29 @@ 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 name or UTC offset 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"]
- * @example bucketRange("2024-03-09T05:00:00Z", "2024-03-12T04:00:00Z", "day", "America/New_York") // ["2024-03-09T05:00:00Z", "2024-03-10T05:00:00Z", "2024-03-11T04:00:00Z"] (the middle day is 23 hours)
- * @example bucketRange("2024-11-02T04:00:00Z", "2024-11-05T05:00:00Z", "day", "America/New_York") // ["2024-11-02T04:00:00Z", "2024-11-03T04:00:00Z", "2024-11-04T05:00:00Z"] (the middle day is 25 hours)
- * @example bucketRange("2024-11-03T04:00:00Z", "2024-11-03T08:00:00Z", "hour", "America/New_York") // ["2024-11-03T04:00:00Z", "2024-11-03T05:00:00Z", "2024-11-03T06:00:00Z", "2024-11-03T07:00:00Z"] (the repeated 01:00 is its own bucket)
- * @example bucketRange("2024-06-14T04:00:00Z", "2024-06-14T04:00:00Z", "day", "America/New_York") // [] (zero length, on a boundary)
- * @example bucketRange("+275760-09-12T23:00:00Z", "+275760-09-13T00:00:00Z", "day", "America/New_York") // ["+275760-09-12T04:00:00Z"] (the next day would start past the last instant; this one is still returned)
+ * @example bucketRange("2024-06-15T03:00:00Z", "2024-06-17T03:00:00Z", "day", "Asia/Kolkata") // ["2024-06-14T18:30:00Z", "2024-06-15T18:30:00Z", "2024-06-16T18:30:00Z"]
+ * @example bucketRange("2024-03-30T00:00:00Z", "2024-04-01T23:00:00Z", "day", "Europe/London") // ["2024-03-30T00:00:00Z", "2024-03-31T00:00:00Z", "2024-03-31T23:00:00Z"] (the middle day is 23 hours)
+ * @example bucketRange("2024-04-05T13:00:00Z", "2024-04-08T14:00:00Z", "day", "Australia/Sydney") // ["2024-04-05T13:00:00Z", "2024-04-06T13:00:00Z", "2024-04-07T14:00:00Z"] (the middle day is 25 hours)
+ * @example bucketRange("2024-04-06T14:00:00Z", "2024-04-06T18:00:00Z", "hour", "Australia/Sydney") // ["2024-04-06T14:00:00Z", "2024-04-06T15:00:00Z", "2024-04-06T16:00:00Z", "2024-04-06T17:00:00Z"] (the repeated 02:00 is its own bucket)
+ * @example bucketRange("2024-06-14T15:00:00Z", "2024-06-14T15:00:00Z", "day", "Asia/Tokyo") // [] (zero length, on a boundary)
+ * @example bucketRange("+275760-09-12T23:00:00Z", "+275760-09-13T00:00:00Z", "day", "America/Sao_Paulo") // ["+275760-09-12T03:00:00Z"] (the next day would start past the last instant; this one is still returned)
  * @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", "days", "Asia/Tokyo") // ["2024-06-14T15:00:00Z", "2024-06-15T15:00:00Z", "2024-06-16T15: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 { instantFrom, nextZonedBucketStart, zonedNextTransition, zonedUnitStart, } from "../../internal/index.js";
+import { Temporal } from "../../internal/temporal.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.
@@ -82,7 +30,7 @@ function nextBucketStartWithinRange(current, unit) {
  * Return the start instant of every `unit` bucket the half-open range `[start, end)` touches,
  * bucketed **in `timeZone`**.
  *
- * This is "group by day in `America/New_York`" over UTC timestamps, done correctly. Buckets
+ * This is "group by day in `Europe/London`" over UTC timestamps, done correctly. Buckets
  * are not uniform in length and that is the point: a day that springs forward is 23 hours and
  * one that falls back is 25, so a daily aggregate built on a fixed 24 hours drifts an hour
  * twice a year, and a container's chargeable days — counted in terminal-local calendar days —
@@ -107,38 +55,47 @@ 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 name or UTC offset 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"]
- * @example bucketRange("2024-03-09T05:00:00Z", "2024-03-12T04:00:00Z", "day", "America/New_York") // ["2024-03-09T05:00:00Z", "2024-03-10T05:00:00Z", "2024-03-11T04:00:00Z"] (the middle day is 23 hours)
- * @example bucketRange("2024-11-02T04:00:00Z", "2024-11-05T05:00:00Z", "day", "America/New_York") // ["2024-11-02T04:00:00Z", "2024-11-03T04:00:00Z", "2024-11-04T05:00:00Z"] (the middle day is 25 hours)
- * @example bucketRange("2024-11-03T04:00:00Z", "2024-11-03T08:00:00Z", "hour", "America/New_York") // ["2024-11-03T04:00:00Z", "2024-11-03T05:00:00Z", "2024-11-03T06:00:00Z", "2024-11-03T07:00:00Z"] (the repeated 01:00 is its own bucket)
- * @example bucketRange("2024-06-14T04:00:00Z", "2024-06-14T04:00:00Z", "day", "America/New_York") // [] (zero length, on a boundary)
- * @example bucketRange("+275760-09-12T23:00:00Z", "+275760-09-13T00:00:00Z", "day", "America/New_York") // ["+275760-09-12T04:00:00Z"] (the next day would start past the last instant; this one is still returned)
+ * @example bucketRange("2024-06-15T03:00:00Z", "2024-06-17T03:00:00Z", "day", "Asia/Kolkata") // ["2024-06-14T18:30:00Z", "2024-06-15T18:30:00Z", "2024-06-16T18:30:00Z"]
+ * @example bucketRange("2024-03-30T00:00:00Z", "2024-04-01T23:00:00Z", "day", "Europe/London") // ["2024-03-30T00:00:00Z", "2024-03-31T00:00:00Z", "2024-03-31T23:00:00Z"] (the middle day is 23 hours)
+ * @example bucketRange("2024-04-05T13:00:00Z", "2024-04-08T14:00:00Z", "day", "Australia/Sydney") // ["2024-04-05T13:00:00Z", "2024-04-06T13:00:00Z", "2024-04-07T14:00:00Z"] (the middle day is 25 hours)
+ * @example bucketRange("2024-04-06T14:00:00Z", "2024-04-06T18:00:00Z", "hour", "Australia/Sydney") // ["2024-04-06T14:00:00Z", "2024-04-06T15:00:00Z", "2024-04-06T16:00:00Z", "2024-04-06T17:00:00Z"] (the repeated 02:00 is its own bucket)
+ * @example bucketRange("2024-06-14T15:00:00Z", "2024-06-14T15:00:00Z", "day", "Asia/Tokyo") // [] (zero length, on a boundary)
+ * @example bucketRange("+275760-09-12T23:00:00Z", "+275760-09-13T00:00:00Z", "day", "America/Sao_Paulo") // ["+275760-09-12T03:00:00Z"] (the next day would start past the last instant; this one is still returned)
  * @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", "days", "Asia/Tokyo") // ["2024-06-14T15:00:00Z", "2024-06-15T15:00:00Z", "2024-06-16T15: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 = instantFrom(start).toZonedDateTimeISO(timeZone);
-        const endZoned = instantFrom(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 type { Temporal } from "@js-temporal/polyfill";
+import type { Temporal } from "../../internal/temporal.js";
 import type { ZoneBucketUnit } from "../../types/index.js";
 /**
  * Floor an instant to the start of the `unit` containing it **in `timeZone`**, and return
@@ -24,21 +24,29 @@ import type { ZoneBucketUnit } from "../../types/index.js";
  * - 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 name or UTC offset 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)
  * @example floorToZone("2024-06-15T03:00:00Z", "day", "UTC") // "2024-06-15T00:00:00Z" (the same instant, a different local day)
  * @example floorToZone("2024-06-15T03:00:00Z", "hour", "Asia/Kathmandu") // "2024-06-15T02:15:00Z" (a +05:45 zone's hour boundary)
- * @example floorToZone("2024-06-15T03:00:00Z", "week", "America/New_York") // "2024-06-10T04:00:00Z" (the Monday)
+ * @example floorToZone("2024-06-15T03:00:00Z", "week", "Asia/Tokyo") // "2024-06-09T15:00:00Z" (the Monday)
  * @example floorToZone("2024-09-08T10:00:00Z", "day", "America/Santiago") // "2024-09-08T04:00:00Z" (local midnight is skipped, so the day starts at 01:00)
  * @example floorToZone("2024-05-15T10:20:30.123Z", "days", "Europe/Berlin") // "2024-05-14T22:00:00Z" (plural unit name)
  * @example floorToZone("2024-06-15T03:00:00Z", "year", "UTC") // "" (not a bucketing unit)
  * @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,6 +1,5 @@
-import { instantFrom, 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";
 /**
@@ -27,35 +26,44 @@ import { resolveDateTimeUnit } from "../../internal/resolveDateTimeUnit.js";
  * - 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 name or UTC offset 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)
  * @example floorToZone("2024-06-15T03:00:00Z", "day", "UTC") // "2024-06-15T00:00:00Z" (the same instant, a different local day)
  * @example floorToZone("2024-06-15T03:00:00Z", "hour", "Asia/Kathmandu") // "2024-06-15T02:15:00Z" (a +05:45 zone's hour boundary)
- * @example floorToZone("2024-06-15T03:00:00Z", "week", "America/New_York") // "2024-06-10T04:00:00Z" (the Monday)
+ * @example floorToZone("2024-06-15T03:00:00Z", "week", "Asia/Tokyo") // "2024-06-09T15:00:00Z" (the Monday)
  * @example floorToZone("2024-09-08T10:00:00Z", "day", "America/Santiago") // "2024-09-08T04:00:00Z" (local midnight is skipped, so the day starts at 01:00)
  * @example floorToZone("2024-05-15T10:20:30.123Z", "days", "Europe/Berlin") // "2024-05-14T22:00:00Z" (plural unit name)
  * @example floorToZone("2024-06-15T03:00:00Z", "year", "UTC") // "" (not a bucketing unit)
  * @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 = instantFrom(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 "";