@northguild/gmt 1.14.2

package/dist/zoned/interval/mergeIntervalsZoned.js

@@ -0,0 +1,77 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { calendarOfAllZonedValues, formatZonedInCalendar, parseCalendarZonedValue, } from "../../internal/index.js";
+import { isValidCalendarZonedInterval } from "./validate/index.js";
+/**
+ * Collapse a list of zoned intervals into the minimum set of non-overlapping intervals.
+ *
+ * - List-form generalization of `intervalUnionZoned`, which is pairwise only.
+ * - Comparison and merging use each interval's instant, so intervals may carry different time
+ *   zones.
+ * - Intervals are merged when they overlap or share an instant exactly (adjacent intervals
+ *   ARE merged).
+ * - Order of the input list does not matter; the result is sorted by start instant. Each merged
+ *   record's `start`/`end` strings carry the time zone of whichever input interval contributed
+ *   that boundary.
+ * - Returns `[]` for an empty list.
+ * - Returns `[]` when `intervals` is not an array, when any element is not a
+ *   `{ start, end }` record of valid ISO ZonedDateTime strings, or when any element has
+ *   `start > end` or a leap-second string.
+ * - Accepts GMT calendar-annotated zoned strings (as produced by `convertZonedToCalendar`) as
+ *   well as bare ISO ones — E7 (issue #152) — but **rejects a mismatched set**: every endpoint in
+ *   the list must name the same calendar system (E7's D4-zoned). This function returns *values*
+ *   the caller reads back as datetimes, and an array whose elements carried different calendar
+ *   tags would be unreadable as a set. A mismatch returns `[]`.
+ * - Output boundaries are re-derived in the resolved calendar via `formatZonedInCalendar`, never
+ *   copied from an input string (E7's D7-zoned).
+ *
+ * @param intervals array of `{ start, end }` records
+ * @returns the minimum set of non-overlapping `{ start, end }` records, sorted by start, or `[]` on invalid input
+ *
+ * @example mergeIntervalsZoned([{ start: "2024-01-01T00:00:00+00:00[UTC]", end: "2024-01-10T00:00:00+00:00[UTC]" }, { start: "2024-01-05T00:00:00+00:00[UTC]", end: "2024-01-15T00:00:00+00:00[UTC]" }]) // [{ start: "2024-01-01T00:00:00+00:00[UTC]", end: "2024-01-15T00:00:00+00:00[UTC]" }]
+ * @example mergeIntervalsZoned([]) // []
+ */
+export function mergeIntervalsZoned(intervals) {
+    if (!Array.isArray(intervals) || intervals.length === 0) {
+        return [];
+    }
+    if (!intervals.every((interval) => interval &&
+        typeof interval === "object" &&
+        typeof interval.start === "string" &&
+        typeof interval.end === "string" &&
+        isValidCalendarZonedInterval(interval.start, interval.end))) {
+        return [];
+    }
+    // D4-zoned reject gate: every endpoint across every interval must agree on a calendar, or there
+    // is no calendar to express the merged boundaries in.
+    const calendar = calendarOfAllZonedValues(intervals.flatMap((interval) => [interval.start, interval.end]));
+    if (!calendar) {
+        return [];
+    }
+    try {
+        const parsed = intervals.map((interval) => ({
+            start: parseCalendarZonedValue(interval.start),
+            end: parseCalendarZonedValue(interval.end),
+        }));
+        parsed.sort((a, b) => Temporal.Instant.compare(a.start.toInstant(), b.start.toInstant()));
+        const merged = [];
+        for (const interval of parsed) {
+            const last = merged[merged.length - 1];
+            if (last &&
+                Temporal.Instant.compare(interval.start.toInstant(), last.end.toInstant()) <= 0) {
+                if (Temporal.Instant.compare(interval.end.toInstant(), last.end.toInstant()) > 0) {
+                    last.end = interval.end;
+                }
+            }
+            else {
+                merged.push({ start: interval.start, end: interval.end });
+            }
+        }
+        return merged.map((interval) => ({
+            start: formatZonedInCalendar(interval.start, calendar),
+            end: formatZonedInCalendar(interval.end, calendar),
+        }));
+    }
+    catch {
+        return [];
+    }
+}

package/dist/zoned/interval/splitIntervalByUnitZoned.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Split a zoned interval into sub-intervals of `amount × unit`.
+ *
+ * - Returns an array of `{ start, end }` records that tile the interval.
+ * - The final sub-interval is trimmed so its `end` never exceeds the original `end`.
+ * - Returns `[{ start, end }]` when `start === end` (zero-length interval).
+ * - Accepts GMT calendar-annotated zoned strings (as produced by `convertZonedToCalendar`) as
+ *   well as bare ISO ones — E7 (issue #152). Stepping by a calendar unit ("1 month") resolves
+ *   against the endpoints' shared calendar when both tags match, and falls back to Gregorian/ISO
+ *   when they mismatch or either endpoint is bare (E7's D5-zoned). Sub-interval boundaries are
+ *   re-derived in the resolved calendar via `formatZonedInCalendar`, never copied from an input
+ *   string (E7's D7-zoned).
+ * - Returns `[]` on invalid input (unparseable start/end, unsupported unit, non-positive amount,
+ *   leap-second strings).
+ *
+ * @param start ISO 8601 zoned datetime string for the interval start
+ * @param end ISO 8601 zoned datetime string for the interval end
+ * @param unit duration unit string — any `DateTimeDurationUnit`
+ * @param amount positive number of units per step
+ * @returns array of `{ start, end }` records, or [] on invalid input
+ *
+ * @example splitIntervalByUnitZoned("2024-01-01T00:00:00+00:00[UTC]", "2024-01-02T00:00:00+00:00[UTC]", "hour", 6) // [{ start: "2024-01-01T00:00:00+00:00[UTC]", end: "2024-01-01T06:00:00+00:00[UTC]" }, { start: "2024-01-01T06:00:00+00:00[UTC]", end: "2024-01-01T12:00:00+00:00[UTC]" }, { start: "2024-01-01T12:00:00+00:00[UTC]", end: "2024-01-01T18:00:00+00:00[UTC]" }, { start: "2024-01-01T18:00:00+00:00[UTC]", end: "2024-01-02T00:00:00+00:00[UTC]" }]
+ * @example splitIntervalByUnitZoned("2024-01-01T00:00:00+00:00[UTC]", "2024-01-01T01:30:00+00:00[UTC]", "hour", 1) // [{ start: "2024-01-01T00:00:00+00:00[UTC]", end: "2024-01-01T01:00:00+00:00[UTC]" }, { start: "2024-01-01T01:00:00+00:00[UTC]", end: "2024-01-01T01:30:00+00:00[UTC]" }]
+ * @example splitIntervalByUnitZoned("2024-01-01T00:00:00+00:00[UTC]", "2024-01-01T00:00:00+00:00[UTC]", "hour", 1) // [{ start: "2024-01-01T00:00:00+00:00[UTC]", end: "2024-01-01T00:00:00+00:00[UTC]" }]
+ * @example splitIntervalByUnitZoned("2024-01-01T00:00:00+00:00[UTC]", "2024-01-02T00:00:00+00:00[UTC]", "hour", 0) // []
+ * @example splitIntervalByUnitZoned("invalid", "2024-01-02T00:00:00+00:00[UTC]", "hour", 1) // []
+ */
+export declare function splitIntervalByUnitZoned(start: string, end: string, unit: string, amount: number): Array<{
+    start: string;
+    end: string;
+}>;

package/dist/zoned/interval/splitIntervalByUnitZoned.js

@@ -0,0 +1,77 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { formatZonedInCalendar, parseCalendarZonedPairForArithmetic, resolveDurationUnit, } from "../../internal/index.js";
+import { isValidCalendarZonedDateTime } from "../validate/isValidCalendarZonedDateTime.js";
+/**
+ * Split a zoned interval into sub-intervals of `amount × unit`.
+ *
+ * - Returns an array of `{ start, end }` records that tile the interval.
+ * - The final sub-interval is trimmed so its `end` never exceeds the original `end`.
+ * - Returns `[{ start, end }]` when `start === end` (zero-length interval).
+ * - Accepts GMT calendar-annotated zoned strings (as produced by `convertZonedToCalendar`) as
+ *   well as bare ISO ones — E7 (issue #152). Stepping by a calendar unit ("1 month") resolves
+ *   against the endpoints' shared calendar when both tags match, and falls back to Gregorian/ISO
+ *   when they mismatch or either endpoint is bare (E7's D5-zoned). Sub-interval boundaries are
+ *   re-derived in the resolved calendar via `formatZonedInCalendar`, never copied from an input
+ *   string (E7's D7-zoned).
+ * - Returns `[]` on invalid input (unparseable start/end, unsupported unit, non-positive amount,
+ *   leap-second strings).
+ *
+ * @param start ISO 8601 zoned datetime string for the interval start
+ * @param end ISO 8601 zoned datetime string for the interval end
+ * @param unit duration unit string — any `DateTimeDurationUnit`
+ * @param amount positive number of units per step
+ * @returns array of `{ start, end }` records, or [] on invalid input
+ *
+ * @example splitIntervalByUnitZoned("2024-01-01T00:00:00+00:00[UTC]", "2024-01-02T00:00:00+00:00[UTC]", "hour", 6) // [{ start: "2024-01-01T00:00:00+00:00[UTC]", end: "2024-01-01T06:00:00+00:00[UTC]" }, { start: "2024-01-01T06:00:00+00:00[UTC]", end: "2024-01-01T12:00:00+00:00[UTC]" }, { start: "2024-01-01T12:00:00+00:00[UTC]", end: "2024-01-01T18:00:00+00:00[UTC]" }, { start: "2024-01-01T18:00:00+00:00[UTC]", end: "2024-01-02T00:00:00+00:00[UTC]" }]
+ * @example splitIntervalByUnitZoned("2024-01-01T00:00:00+00:00[UTC]", "2024-01-01T01:30:00+00:00[UTC]", "hour", 1) // [{ start: "2024-01-01T00:00:00+00:00[UTC]", end: "2024-01-01T01:00:00+00:00[UTC]" }, { start: "2024-01-01T01:00:00+00:00[UTC]", end: "2024-01-01T01:30:00+00:00[UTC]" }]
+ * @example splitIntervalByUnitZoned("2024-01-01T00:00:00+00:00[UTC]", "2024-01-01T00:00:00+00:00[UTC]", "hour", 1) // [{ start: "2024-01-01T00:00:00+00:00[UTC]", end: "2024-01-01T00:00:00+00:00[UTC]" }]
+ * @example splitIntervalByUnitZoned("2024-01-01T00:00:00+00:00[UTC]", "2024-01-02T00:00:00+00:00[UTC]", "hour", 0) // []
+ * @example splitIntervalByUnitZoned("invalid", "2024-01-02T00:00:00+00:00[UTC]", "hour", 1) // []
+ */
+export function splitIntervalByUnitZoned(start, end, unit, amount) {
+    if (!isValidCalendarZonedDateTime(start) ||
+        !isValidCalendarZonedDateTime(end)) {
+        return [];
+    }
+    if (typeof unit !== "string") {
+        return [];
+    }
+    const resolvedUnit = resolveDurationUnit(unit);
+    if (!resolvedUnit) {
+        return [];
+    }
+    if (!Number.isFinite(amount) || amount <= 0) {
+        return [];
+    }
+    try {
+        const { calendar, a: startVal, b: endVal, } = parseCalendarZonedPairForArithmetic(start, end);
+        if (Temporal.ZonedDateTime.compare(startVal, endVal) > 0) {
+            return [];
+        }
+        if (Temporal.ZonedDateTime.compare(startVal, endVal) === 0) {
+            return [
+                {
+                    start: formatZonedInCalendar(startVal, calendar),
+                    end: formatZonedInCalendar(endVal, calendar),
+                },
+            ];
+        }
+        const result = [];
+        for (let current = startVal; Temporal.ZonedDateTime.compare(current, endVal) < 0;) {
+            const next = current.add({ [resolvedUnit]: amount });
+            if (Temporal.ZonedDateTime.compare(next, current) === 0) {
+                return [];
+            }
+            const sliceEnd = Temporal.ZonedDateTime.compare(next, endVal) > 0 ? endVal : next;
+            result.push({
+                start: formatZonedInCalendar(current, calendar),
+                end: formatZonedInCalendar(sliceEnd, calendar),
+            });
+            current = next;
+        }
+        return result;
+    }
+    catch {
+        return [];
+    }
+}

package/dist/zoned/interval/validate/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./isValidCalendarZonedInterval.js";
+export * from "./isValidZonedInterval.js";

package/dist/zoned/interval/validate/index.js

@@ -0,0 +1,2 @@
+export * from "./isValidCalendarZonedInterval.js";
+export * from "./isValidZonedInterval.js";

package/dist/zoned/interval/validate/isValidCalendarZonedInterval.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Return true if `start` and `end` form a valid GMT zoned interval — both parseable as bare ISO
+ * or GMT calendar-annotated ZonedDateTime strings, and the instant at `start` is <= the instant
+ * at `end`.
+ *
+ * - Parallel to `isValidZonedInterval`, which is deliberately left unchanged and still rejects
+ *   every `[u-ca=...]` annotation (E7, issue #152). Only the calendar-aware `zoned/interval/*`
+ *   functions gate on this one.
+ * - **Mixed calendars are accepted** (E7's D4-zoned, matching E5's D4): ordering is
+ *   calendar-independent. Verified against `@js-temporal/polyfill@0.5.1` —
+ *   `Temporal.Instant` carries no calendar field at all, and `ZonedDateTime.compare` /
+ *   `Instant.compare` both return `0` for the same instant expressed in hebrew, islamic-civil,
+ *   japanese and iso8601. A Hebrew start with an Islamic end is a well-formed interval.
+ * - Equal `start === end` is valid.
+ * - Comparison is done by instant, so intervals spanning DST transitions are compared by
+ *   absolute time.
+ * - Rejects Temporal's `[timeZone][u-ca=...]` ordering, leap seconds, non-strings, and any
+ *   unparseable endpoint.
+ *
+ * @param start ISO or GMT calendar-annotated ZonedDateTime string (interval start)
+ * @param end ISO or GMT calendar-annotated ZonedDateTime string (interval end)
+ * @returns true if start and end form a valid zoned interval, or false on invalid input
+ *
+ * @example isValidCalendarZonedInterval("2024-01-01T10:00:00+00:00[UTC]", "2024-12-31T23:59:59+00:00[UTC]") // true
+ * @example isValidCalendarZonedInterval("5784-06-15T14:30:00-05:00[u-ca=hebrew][America/New_York]", "5784-07-15T14:30:00-04:00[u-ca=hebrew][America/New_York]") // true
+ * @example isValidCalendarZonedInterval("5784-06-15T14:30:00-05:00[u-ca=hebrew][America/New_York]", "1445-09-15T14:30:00-04:00[u-ca=islamic-civil][America/New_York]") // true (mixed calendars accepted)
+ * @example isValidCalendarZonedInterval("2024-12-31T23:59:59+00:00[UTC]", "2024-01-01T10:00:00+00:00[UTC]") // false (start after end)
+ * @example isValidCalendarZonedInterval("2024-01-01T10:00:00+00:00[UTC][u-ca=hebrew]", "2024-12-31T23:59:59+00:00[UTC]") // false (Temporal's segment ordering)
+ * @example isValidCalendarZonedInterval("invalid", "2024-12-31T23:59:59+00:00[UTC]") // false
+ */
+export declare function isValidCalendarZonedInterval(start: string, end: string): boolean;

package/dist/zoned/interval/validate/isValidCalendarZonedInterval.js

@@ -0,0 +1,45 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { parseCalendarZonedValue } from "../../../internal/index.js";
+/**
+ * Return true if `start` and `end` form a valid GMT zoned interval — both parseable as bare ISO
+ * or GMT calendar-annotated ZonedDateTime strings, and the instant at `start` is <= the instant
+ * at `end`.
+ *
+ * - Parallel to `isValidZonedInterval`, which is deliberately left unchanged and still rejects
+ *   every `[u-ca=...]` annotation (E7, issue #152). Only the calendar-aware `zoned/interval/*`
+ *   functions gate on this one.
+ * - **Mixed calendars are accepted** (E7's D4-zoned, matching E5's D4): ordering is
+ *   calendar-independent. Verified against `@js-temporal/polyfill@0.5.1` —
+ *   `Temporal.Instant` carries no calendar field at all, and `ZonedDateTime.compare` /
+ *   `Instant.compare` both return `0` for the same instant expressed in hebrew, islamic-civil,
+ *   japanese and iso8601. A Hebrew start with an Islamic end is a well-formed interval.
+ * - Equal `start === end` is valid.
+ * - Comparison is done by instant, so intervals spanning DST transitions are compared by
+ *   absolute time.
+ * - Rejects Temporal's `[timeZone][u-ca=...]` ordering, leap seconds, non-strings, and any
+ *   unparseable endpoint.
+ *
+ * @param start ISO or GMT calendar-annotated ZonedDateTime string (interval start)
+ * @param end ISO or GMT calendar-annotated ZonedDateTime string (interval end)
+ * @returns true if start and end form a valid zoned interval, or false on invalid input
+ *
+ * @example isValidCalendarZonedInterval("2024-01-01T10:00:00+00:00[UTC]", "2024-12-31T23:59:59+00:00[UTC]") // true
+ * @example isValidCalendarZonedInterval("5784-06-15T14:30:00-05:00[u-ca=hebrew][America/New_York]", "5784-07-15T14:30:00-04:00[u-ca=hebrew][America/New_York]") // true
+ * @example isValidCalendarZonedInterval("5784-06-15T14:30:00-05:00[u-ca=hebrew][America/New_York]", "1445-09-15T14:30:00-04:00[u-ca=islamic-civil][America/New_York]") // true (mixed calendars accepted)
+ * @example isValidCalendarZonedInterval("2024-12-31T23:59:59+00:00[UTC]", "2024-01-01T10:00:00+00:00[UTC]") // false (start after end)
+ * @example isValidCalendarZonedInterval("2024-01-01T10:00:00+00:00[UTC][u-ca=hebrew]", "2024-12-31T23:59:59+00:00[UTC]") // false (Temporal's segment ordering)
+ * @example isValidCalendarZonedInterval("invalid", "2024-12-31T23:59:59+00:00[UTC]") // false
+ */
+export function isValidCalendarZonedInterval(start, end) {
+    if (typeof start !== "string" || typeof end !== "string") {
+        return false;
+    }
+    try {
+        const startInstant = parseCalendarZonedValue(start).toInstant();
+        const endInstant = parseCalendarZonedValue(end).toInstant();
+        return Temporal.Instant.compare(startInstant, endInstant) <= 0;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/zoned/interval/validate/isValidZonedInterval.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Return true if `start` and `end` form a valid zoned interval — both parseable as
+ * ISO ZonedDateTime strings and the instant at `start` is <= the instant at `end`.
+ *
+ * - Both inputs must be valid ISO 8601 zoned datetime strings.
+ * - Equal `start === end` is valid.
+ * - Comparison is done by instant, so intervals spanning DST transitions are compared
+ *   by absolute time.
+ * - Rejects any `[u-ca=...]` calendar annotation (E5 issue #78, decision of record D2) — see
+ *   `isValidZonedDateTime`'s JSDoc for why.
+ * - Invalid input, malformed strings, or leap-second strings return `false`.
+ *
+ * @param start ISO ZonedDateTime string (interval start)
+ * @param end ISO ZonedDateTime string (interval end)
+ * @returns true if start and end form a valid zoned interval, or false on invalid input
+ *
+ * @example isValidZonedInterval("2024-01-01T10:00:00+00:00[UTC]", "2024-12-31T23:59:59+00:00[UTC]") // true
+ * @example isValidZonedInterval("2024-06-15T12:00:00-04:00[America/New_York]", "2024-06-15T12:00:00-04:00[America/New_York]") // true
+ * @example isValidZonedInterval("2024-12-31T23:59:59+00:00[UTC]", "2024-01-01T10:00:00+00:00[UTC]") // false
+ * @example isValidZonedInterval("2024-01-01T10:00:00+00:00[UTC][u-ca=hebrew]", "2024-12-31T23:59:59+00:00[UTC]") // false (calendar annotation rejected)
+ * @example isValidZonedInterval("invalid", "2024-12-31T23:59:59+00:00[UTC]") // false
+ */
+export declare function isValidZonedInterval(start: string, end: string): boolean;

package/dist/zoned/interval/validate/isValidZonedInterval.js

@@ -0,0 +1,44 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { hasCalendarAnnotation } from "../../../internal/index.js";
+import { isLeapSecond } from "../../../plain/validate/isLeapSecond.js";
+/**
+ * Return true if `start` and `end` form a valid zoned interval — both parseable as
+ * ISO ZonedDateTime strings and the instant at `start` is <= the instant at `end`.
+ *
+ * - Both inputs must be valid ISO 8601 zoned datetime strings.
+ * - Equal `start === end` is valid.
+ * - Comparison is done by instant, so intervals spanning DST transitions are compared
+ *   by absolute time.
+ * - Rejects any `[u-ca=...]` calendar annotation (E5 issue #78, decision of record D2) — see
+ *   `isValidZonedDateTime`'s JSDoc for why.
+ * - Invalid input, malformed strings, or leap-second strings return `false`.
+ *
+ * @param start ISO ZonedDateTime string (interval start)
+ * @param end ISO ZonedDateTime string (interval end)
+ * @returns true if start and end form a valid zoned interval, or false on invalid input
+ *
+ * @example isValidZonedInterval("2024-01-01T10:00:00+00:00[UTC]", "2024-12-31T23:59:59+00:00[UTC]") // true
+ * @example isValidZonedInterval("2024-06-15T12:00:00-04:00[America/New_York]", "2024-06-15T12:00:00-04:00[America/New_York]") // true
+ * @example isValidZonedInterval("2024-12-31T23:59:59+00:00[UTC]", "2024-01-01T10:00:00+00:00[UTC]") // false
+ * @example isValidZonedInterval("2024-01-01T10:00:00+00:00[UTC][u-ca=hebrew]", "2024-12-31T23:59:59+00:00[UTC]") // false (calendar annotation rejected)
+ * @example isValidZonedInterval("invalid", "2024-12-31T23:59:59+00:00[UTC]") // false
+ */
+export function isValidZonedInterval(start, end) {
+    if (typeof start !== "string" || typeof end !== "string") {
+        return false;
+    }
+    if (isLeapSecond(start) ||
+        isLeapSecond(end) ||
+        hasCalendarAnnotation(start) ||
+        hasCalendarAnnotation(end)) {
+        return false;
+    }
+    try {
+        const startInstant = Temporal.ZonedDateTime.from(start).toInstant();
+        const endInstant = Temporal.ZonedDateTime.from(end).toInstant();
+        return Temporal.Instant.compare(startInstant, endInstant) <= 0;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/zoned/map/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./mapZonedDatesInRange.js";
+export * from "./mapZonedHoursInDay.js";

package/dist/zoned/map/index.js

@@ -0,0 +1,2 @@
+export * from "./mapZonedDatesInRange.js";
+export * from "./mapZonedHoursInDay.js";

package/dist/zoned/map/mapZonedDatesInRange.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Return an array of plain ISO date strings covering the inclusive date range between two zoned datetimes.
+ *
+ * - Both datetimes must have the same timezone.
+ * - Returns [] for invalid inputs, mismatched timezones, start > end, or invalid step.
+ *
+ * @param startZonedDateTime start zoned ISO 8601 datetime string
+ * @param endZonedDateTime end zoned ISO 8601 datetime string
+ * @param stepDays optional positive integer step in days
+ * @returns array of ISO date strings or [] when invalid
+ *
+ * @example mapZonedDatesInRange("2024-02-28T12:00:00+00:00[UTC]", "2024-03-02T12:00:00+00:00[UTC]") // ["2024-02-28", "2024-02-29", "2024-03-01", "2024-03-02"]
+ * @example mapZonedDatesInRange("2024-02-28T12:00:00+00:00[UTC]", "2024-03-02T12:00:00+00:00[UTC]", 2) // ["2024-02-28", "2024-03-01"]
+ * @example mapZonedDatesInRange("invalid", "2024-03-02T12:00:00+00:00[UTC]") // []
+ */
+export declare function mapZonedDatesInRange(startZonedDateTime: string, endZonedDateTime: string, ...stepDaysInput: [stepDays?: number]): string[];

package/dist/zoned/map/mapZonedDatesInRange.js

@@ -0,0 +1,56 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidZonedDateTime } from "../validate/index.js";
+/**
+ * Return an array of plain ISO date strings covering the inclusive date range between two zoned datetimes.
+ *
+ * - Both datetimes must have the same timezone.
+ * - Returns [] for invalid inputs, mismatched timezones, start > end, or invalid step.
+ *
+ * @param startZonedDateTime start zoned ISO 8601 datetime string
+ * @param endZonedDateTime end zoned ISO 8601 datetime string
+ * @param stepDays optional positive integer step in days
+ * @returns array of ISO date strings or [] when invalid
+ *
+ * @example mapZonedDatesInRange("2024-02-28T12:00:00+00:00[UTC]", "2024-03-02T12:00:00+00:00[UTC]") // ["2024-02-28", "2024-02-29", "2024-03-01", "2024-03-02"]
+ * @example mapZonedDatesInRange("2024-02-28T12:00:00+00:00[UTC]", "2024-03-02T12:00:00+00:00[UTC]", 2) // ["2024-02-28", "2024-03-01"]
+ * @example mapZonedDatesInRange("invalid", "2024-03-02T12:00:00+00:00[UTC]") // []
+ */
+export function mapZonedDatesInRange(startZonedDateTime, endZonedDateTime, ...stepDaysInput) {
+    const resolvedStepDays = stepDaysInput.length === 0 ? 1 : stepDaysInput[0];
+    if (typeof resolvedStepDays !== "number" ||
+        !Number.isInteger(resolvedStepDays) ||
+        resolvedStepDays <= 0) {
+        return [];
+    }
+    if (!isValidZonedDateTime(startZonedDateTime) ||
+        !isValidZonedDateTime(endZonedDateTime)) {
+        return [];
+    }
+    try {
+        let start;
+        let end;
+        try {
+            start = Temporal.ZonedDateTime.from(startZonedDateTime);
+            end = Temporal.ZonedDateTime.from(endZonedDateTime);
+        }
+        catch {
+            return [];
+        }
+        if (start.timeZoneId !== end.timeZoneId) {
+            return [];
+        }
+        const startDate = start.toPlainDate();
+        const endDate = end.toPlainDate();
+        if (Temporal.PlainDate.compare(startDate, endDate) === 1) {
+            return [];
+        }
+        const result = [];
+        for (let current = startDate; Temporal.PlainDate.compare(current, endDate) <= 0; current = current.add({ days: resolvedStepDays })) {
+            result.push(current.toString());
+        }
+        return result;
+    }
+    catch {
+        return [];
+    }
+}

package/dist/zoned/map/mapZonedHoursInDay.d.ts

@@ -0,0 +1,23 @@
+import type { Disambiguation, Offset } from "../../types/index.js";
+/**
+ * Return an array of zoned datetime strings representing each hour boundary for the 24-hour window starting at midnight of the anchor's local day.
+ *
+ * - Handles DST transitions by skipping non-existent hours in the loop (independent of `disambiguation`/`offset` below — arithmetic `.add()` never consults either option, it always resolves as Temporal's default).
+ * - `disambiguation` controls DST gap/overlap resolution only for the midnight anchor itself, on the rare zone/date where local midnight is itself ambiguous (most IANA zones transition at 2am/3am, not midnight): "compatible" (default, matches Temporal's default), "earlier", "later", or "reject" (throws, resulting in `[]`).
+ * - `offset` controls whether the source's existing UTC offset is kept when computing the midnight anchor: "prefer" (Temporal's own default — keeps the source offset whenever still valid for the target midnight, which **makes `disambiguation` inert in that case**; note this is not universal — if the source's offset isn't valid for midnight at all (e.g. midnight itself falls inside a gap), `"prefer"` still throws/resolves via `disambiguation` same as `"ignore"` would), "use", "ignore" (**this function's default** — always recomputes from time zone + local time, discarding the stale offset), or "reject" (throws if the source offset is invalid for midnight, independent of `disambiguation`). Leave `offset` at its default unless you specifically need Temporal's raw `.with()` semantics.
+ * - Returns [] for invalid input.
+ *
+ * @param anchor zoned ISO 8601 datetime string used as anchor
+ * @param optionsArg optional: disambiguation ("compatible" | "earlier" | "later" | "reject"), offset ("prefer" | "use" | "ignore" | "reject", default "ignore")
+ * @returns array of zoned ISO 8601 strings for each hour in the day
+ *
+ * @example mapZonedHoursInDay("2024-02-29T12:34:56.789+00:00[UTC]") // ["2024-02-29T00:00:00+00:00[UTC]", "2024-02-29T01:00:00+00:00[UTC]", ..., "2024-02-29T23:00:00+00:00[UTC]"]
+ * @example mapZonedHoursInDay("2024-03-10T12:34:56.789-05:00[America/New_York]") // ["2024-03-10T00:00:00-05:00[America/New_York]", ...] (skips 2 AM due to DST; unaffected by `disambiguation` since this gap is inside the loop's arithmetic, not the anchor)
+ * @example mapZonedHoursInDay("2018-11-04T12:00:00-02:00[America/Sao_Paulo]", { disambiguation: "reject" }) // [] (midnight itself is the DST transition in this historical Brazil zone/date, so the anchor is ambiguous and "reject" throws)
+ * @example mapZonedHoursInDay("2018-11-04T12:00:00-02:00[America/Sao_Paulo]", { disambiguation: "reject", offset: "prefer" }) // [] (the source's -02:00 offset is also invalid at midnight here, so even "prefer" falls through to disambiguation and "reject" still throws — contrast with startOfZoned's Nov 3 America/New_York example, where "prefer" IS valid at the target time and suppresses disambiguation)
+ * @example mapZonedHoursInDay("invalid") // []
+ */
+export declare function mapZonedHoursInDay(anchor: string, optionsArg?: {
+    disambiguation?: Disambiguation;
+    offset?: Offset;
+}): string[];

package/dist/zoned/map/mapZonedHoursInDay.js

@@ -0,0 +1,47 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidZonedDateTime } from "../validate/index.js";
+/**
+ * Return an array of zoned datetime strings representing each hour boundary for the 24-hour window starting at midnight of the anchor's local day.
+ *
+ * - Handles DST transitions by skipping non-existent hours in the loop (independent of `disambiguation`/`offset` below — arithmetic `.add()` never consults either option, it always resolves as Temporal's default).
+ * - `disambiguation` controls DST gap/overlap resolution only for the midnight anchor itself, on the rare zone/date where local midnight is itself ambiguous (most IANA zones transition at 2am/3am, not midnight): "compatible" (default, matches Temporal's default), "earlier", "later", or "reject" (throws, resulting in `[]`).
+ * - `offset` controls whether the source's existing UTC offset is kept when computing the midnight anchor: "prefer" (Temporal's own default — keeps the source offset whenever still valid for the target midnight, which **makes `disambiguation` inert in that case**; note this is not universal — if the source's offset isn't valid for midnight at all (e.g. midnight itself falls inside a gap), `"prefer"` still throws/resolves via `disambiguation` same as `"ignore"` would), "use", "ignore" (**this function's default** — always recomputes from time zone + local time, discarding the stale offset), or "reject" (throws if the source offset is invalid for midnight, independent of `disambiguation`). Leave `offset` at its default unless you specifically need Temporal's raw `.with()` semantics.
+ * - Returns [] for invalid input.
+ *
+ * @param anchor zoned ISO 8601 datetime string used as anchor
+ * @param optionsArg optional: disambiguation ("compatible" | "earlier" | "later" | "reject"), offset ("prefer" | "use" | "ignore" | "reject", default "ignore")
+ * @returns array of zoned ISO 8601 strings for each hour in the day
+ *
+ * @example mapZonedHoursInDay("2024-02-29T12:34:56.789+00:00[UTC]") // ["2024-02-29T00:00:00+00:00[UTC]", "2024-02-29T01:00:00+00:00[UTC]", ..., "2024-02-29T23:00:00+00:00[UTC]"]
+ * @example mapZonedHoursInDay("2024-03-10T12:34:56.789-05:00[America/New_York]") // ["2024-03-10T00:00:00-05:00[America/New_York]", ...] (skips 2 AM due to DST; unaffected by `disambiguation` since this gap is inside the loop's arithmetic, not the anchor)
+ * @example mapZonedHoursInDay("2018-11-04T12:00:00-02:00[America/Sao_Paulo]", { disambiguation: "reject" }) // [] (midnight itself is the DST transition in this historical Brazil zone/date, so the anchor is ambiguous and "reject" throws)
+ * @example mapZonedHoursInDay("2018-11-04T12:00:00-02:00[America/Sao_Paulo]", { disambiguation: "reject", offset: "prefer" }) // [] (the source's -02:00 offset is also invalid at midnight here, so even "prefer" falls through to disambiguation and "reject" still throws — contrast with startOfZoned's Nov 3 America/New_York example, where "prefer" IS valid at the target time and suppresses disambiguation)
+ * @example mapZonedHoursInDay("invalid") // []
+ */
+export function mapZonedHoursInDay(anchor, optionsArg) {
+    if (!isValidZonedDateTime(anchor)) {
+        return [];
+    }
+    const disambiguation = optionsArg?.disambiguation ?? "compatible";
+    const offset = optionsArg?.offset ?? "ignore";
+    try {
+        const zonedDateTime = Temporal.ZonedDateTime.from(anchor);
+        const start = zonedDateTime.with({
+            hour: 0,
+            minute: 0,
+            second: 0,
+            millisecond: 0,
+            microsecond: 0,
+            nanosecond: 0,
+        }, { disambiguation, offset });
+        const nextDay = start.add({ days: 1 });
+        const result = [];
+        for (let current = start; Temporal.Instant.compare(current.toInstant(), nextDay.toInstant()) < 0; current = current.add({ hours: 1 })) {
+            result.push(current.toString());
+        }
+        return result;
+    }
+    catch {
+        return [];
+    }
+}

package/dist/zoned/parse/getZonedOffset.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Extract the UTC offset from an ISO 8601 zoned datetime string.
+ *
+ * - Returns the offset in Temporal's ±HH:MM string form.
+ * - This is a value-taking accessor (per J0b's `get/` rule), so it lives in
+ *   `parse/` alongside `parseTimeZoneFromZoned`, not `get/`.
+ * - Returns "" for invalid input.
+ *
+ * @param value zoned ISO 8601 datetime string
+ * @returns offset string (e.g. "-04:00"), or "" on invalid input
+ *
+ * @example getZonedOffset("2024-02-29T12:34:56.789+00:00[UTC]") // "+00:00"
+ * @example getZonedOffset("2024-07-15T12:00:00-04:00[America/New_York]") // "-04:00"
+ * @example getZonedOffset("2024-05-15T12:00:00+05:45[Asia/Kathmandu]") // "+05:45"
+ * @example getZonedOffset("invalid") // ""
+ */
+export declare function getZonedOffset(value: string): string;

package/dist/zoned/parse/getZonedOffset.js

@@ -0,0 +1,29 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidZonedDateTime } from "../validate/index.js";
+/**
+ * Extract the UTC offset from an ISO 8601 zoned datetime string.
+ *
+ * - Returns the offset in Temporal's ±HH:MM string form.
+ * - This is a value-taking accessor (per J0b's `get/` rule), so it lives in
+ *   `parse/` alongside `parseTimeZoneFromZoned`, not `get/`.
+ * - Returns "" for invalid input.
+ *
+ * @param value zoned ISO 8601 datetime string
+ * @returns offset string (e.g. "-04:00"), or "" on invalid input
+ *
+ * @example getZonedOffset("2024-02-29T12:34:56.789+00:00[UTC]") // "+00:00"
+ * @example getZonedOffset("2024-07-15T12:00:00-04:00[America/New_York]") // "-04:00"
+ * @example getZonedOffset("2024-05-15T12:00:00+05:45[Asia/Kathmandu]") // "+05:45"
+ * @example getZonedOffset("invalid") // ""
+ */
+export function getZonedOffset(value) {
+    if (!isValidZonedDateTime(value)) {
+        return "";
+    }
+    try {
+        return Temporal.ZonedDateTime.from(value).offset;
+    }
+    catch {
+        return "";
+    }
+}

package/dist/zoned/parse/getZonedOffsetAs.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Unit a zoned value's UTC offset can be read as via `getZonedOffsetAs`.
+ */
+export type ZonedOffsetUnit = "minutes" | "nanoseconds";
+/**
+ * Read a zoned value's UTC offset as a number, in the given unit.
+ *
+ * - Subsumes what would otherwise be `getZonedOffsetMinutes` /
+ *   `getZonedOffsetNanoseconds` — one differently-scaled reading of the same
+ *   underlying quantity through a single parameterized call, following J8's
+ *   `getDurationUnit(value, unit)` precedent (Decision 5).
+ * - "nanoseconds" reads Temporal's `offsetNanoseconds` directly.
+ * - "minutes" divides by 60e9 — every IANA offset is a whole number of
+ *   minutes, so this never truncates a fraction.
+ * - Negative offsets (west of UTC) return a negative number.
+ * - Returns null on invalid `value` or `unit`.
+ *
+ * @param value zoned ISO 8601 datetime string
+ * @param unit "minutes" | "nanoseconds"
+ * @returns the offset in the requested unit, or null on invalid input
+ *
+ * @example getZonedOffsetAs("2024-07-15T12:00:00-04:00[America/New_York]", "minutes") // -240
+ * @example getZonedOffsetAs("2024-05-15T12:00:00+05:45[Asia/Kathmandu]", "minutes") // 345
+ * @example getZonedOffsetAs("2024-02-29T12:00:00+00:00[UTC]", "nanoseconds") // 0
+ * @example getZonedOffsetAs("2024-07-15T12:00:00-04:00[America/New_York]", "nanoseconds") // -14400000000000
+ * @example getZonedOffsetAs("invalid", "minutes") // null
+ * @example getZonedOffsetAs("2024-02-29T12:00:00+00:00[UTC]", "fortnights" as never) // null
+ */
+export declare function getZonedOffsetAs(value: string, unit: ZonedOffsetUnit): number | null;

package/dist/zoned/parse/getZonedOffsetAs.js

@@ -0,0 +1,44 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidZonedDateTime } from "../validate/index.js";
+const NANOSECONDS_PER_MINUTE = 60_000_000_000;
+function isValidZonedOffsetUnit(unit) {
+    return unit === "minutes" || unit === "nanoseconds";
+}
+/**
+ * Read a zoned value's UTC offset as a number, in the given unit.
+ *
+ * - Subsumes what would otherwise be `getZonedOffsetMinutes` /
+ *   `getZonedOffsetNanoseconds` — one differently-scaled reading of the same
+ *   underlying quantity through a single parameterized call, following J8's
+ *   `getDurationUnit(value, unit)` precedent (Decision 5).
+ * - "nanoseconds" reads Temporal's `offsetNanoseconds` directly.
+ * - "minutes" divides by 60e9 — every IANA offset is a whole number of
+ *   minutes, so this never truncates a fraction.
+ * - Negative offsets (west of UTC) return a negative number.
+ * - Returns null on invalid `value` or `unit`.
+ *
+ * @param value zoned ISO 8601 datetime string
+ * @param unit "minutes" | "nanoseconds"
+ * @returns the offset in the requested unit, or null on invalid input
+ *
+ * @example getZonedOffsetAs("2024-07-15T12:00:00-04:00[America/New_York]", "minutes") // -240
+ * @example getZonedOffsetAs("2024-05-15T12:00:00+05:45[Asia/Kathmandu]", "minutes") // 345
+ * @example getZonedOffsetAs("2024-02-29T12:00:00+00:00[UTC]", "nanoseconds") // 0
+ * @example getZonedOffsetAs("2024-07-15T12:00:00-04:00[America/New_York]", "nanoseconds") // -14400000000000
+ * @example getZonedOffsetAs("invalid", "minutes") // null
+ * @example getZonedOffsetAs("2024-02-29T12:00:00+00:00[UTC]", "fortnights" as never) // null
+ */
+export function getZonedOffsetAs(value, unit) {
+    if (!isValidZonedDateTime(value) || !isValidZonedOffsetUnit(unit)) {
+        return null;
+    }
+    try {
+        const { offsetNanoseconds } = Temporal.ZonedDateTime.from(value);
+        return unit === "nanoseconds"
+            ? offsetNanoseconds
+            : offsetNanoseconds / NANOSECONDS_PER_MINUTE;
+    }
+    catch {
+        return null;
+    }
+}