@northguild/gmt 1.17.0 → 1.19.0

package/dist/internal/readSetFields.js

@@ -0,0 +1,179 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isObject } from "./isObject.js";
+/** The date fields `setDate` takes. */
+export const DATE_FIELDS = ["year", "month", "monthCode", "day"];
+/** The time fields `setTime` takes. */
+export const TIME_FIELDS = [
+    "hour",
+    "minute",
+    "second",
+    "millisecond",
+    "microsecond",
+    "nanosecond",
+];
+/** The fields `setDateTime`, `setUtc`, `setUnix` and `setZoned` take. */
+export const DATE_TIME_FIELDS = [...DATE_FIELDS, ...TIME_FIELDS];
+/**
+ * Every property TC39 Temporal's `with` methods read from their argument, in the order they read
+ * them: `calendar` and `timeZone` first, which IsPartialTemporalObject (13.24) refuses, then the
+ * date and time fields and the `offset` that `ZonedDateTime.prototype.with` reads, in code-unit
+ * order. PrepareCalendarFields (12.3.3) sorts them so for every `with` that takes a date, and
+ * ToTemporalTimeRecord (4.5.12), which `PlainTime.prototype.with` uses, reads its six fields in
+ * the same order. The list adds the era fields,
+ * which `with` never reads for the ISO 8601 calendar (CalendarExtraFields returns none) and which
+ * GMT reads only to refuse them.
+ */
+const WITH_PROPERTY_NAMES = [
+    "calendar",
+    "timeZone",
+    "day",
+    "era",
+    "eraYear",
+    "hour",
+    "microsecond",
+    "millisecond",
+    "minute",
+    "month",
+    "monthCode",
+    "nanosecond",
+    "offset",
+    "second",
+    "year",
+];
+/** The one field whose value is a string; every other field a `set*` function takes is a number. */
+const STRING_FIELD = "monthCode";
+/**
+ * For each Temporal class whose objects hold a date or a time (the internal slots TC39
+ * IsPartialTemporalObject tests), a getter that throws for any receiver without that slot.
+ */
+const BRANDED_GETTERS = [
+    ["PlainDate", "calendarId"],
+    ["PlainDateTime", "calendarId"],
+    ["PlainMonthDay", "calendarId"],
+    ["PlainYearMonth", "calendarId"],
+    ["ZonedDateTime", "calendarId"],
+    ["PlainTime", "hour"],
+];
+/** Whether `value` holds the internal slot of one class of `namespace`. */
+function isObjectOf(namespace, value) {
+    return BRANDED_GETTERS.some(([name, key]) => {
+        const prototype = namespace[name]?.prototype;
+        const getter = isObject(prototype)
+            ? Object.getOwnPropertyDescriptor(prototype, key)?.get
+            : undefined;
+        if (typeof getter !== "function") {
+            return false;
+        }
+        try {
+            getter.call(value);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    });
+}
+/**
+ * Whether `value` is an object of the Temporal the host provides on `globalThis`, if any. A
+ * malformed host Temporal recognises nothing, so it never changes the result for a field object.
+ */
+function isHostTemporalObject(value) {
+    try {
+        const host = globalThis.Temporal;
+        return (isObject(host) &&
+            host !== Temporal &&
+            isObjectOf(host, value));
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Whether `value` is a Temporal object that holds a date or a time, from the polyfill GMT uses or
+ * from a Temporal the host provides. The test is the one a class's own getter makes: it reads the
+ * internal slot, so neither the prototype chain nor any property of `value` decides it.
+ *
+ * The check calls up to six getters, twelve with a host Temporal, and a throwing getter is slow, so
+ * it is skipped when the prototype is `Object.prototype`, `null` or `Function.prototype`: a plain
+ * object, an `Object.create(null)` object or a function, which no Temporal class makes.
+ *
+ * Limits:
+ * - An object from a second copy of the polyfill that is not on `globalThis` is not detected and
+ *   is read as a field bag, which is also what TC39 IsPartialTemporalObject (13.24) does with an
+ *   object that lacks this polyfill's internal slots.
+ * - A Temporal object whose prototype was swapped to one of the three above is not detected
+ *   either. Its getters are then out of reach, so it reads as setting nothing and the function
+ *   returns its value unchanged (accepted by owner decision for the speed of the plain case).
+ */
+function isTemporalDateOrTimeObject(value) {
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype === Object.prototype ||
+        prototype === null ||
+        prototype === Function.prototype) {
+        return false;
+    }
+    return (isObjectOf(Temporal, value) ||
+        isHostTemporalObject(value));
+}
+/** Whether `value` is one Temporal reads for `name` without converting it. */
+function isFieldValue(name, value) {
+    return name === STRING_FIELD
+        ? typeof value === "string"
+        : typeof value === "number" && Number.isInteger(value);
+}
+/**
+ * Read the `fields` argument of a `set*` function the way Temporal's `with` reads it, and return
+ * the values as a fresh plain object that holds only the fields the function takes.
+ *
+ * The check and the read are one pass, so nothing reaches Temporal that was not checked:
+ *
+ * - `fields` must be an Object (`isObject`), a function included, and not a Temporal object that
+ *   holds a date or a time (TC39 IsPartialTemporalObject).
+ * - An own enumerable string key outside `allowedFields` returns `null`, whatever its value: the guard
+ *   against a misspelt key. A symbol key is ignored.
+ * - Each property `with` reads is read once with an ordinary property get, in the order `with`
+ *   reads them, so an inherited, non-enumerable or getter field applies. `undefined` means absent.
+ *   A defined property outside `allowedFields` (another type's field, an era, an offset, a
+ *   `calendar` or a `timeZone`) returns `null`.
+ * - A value is not converted: `monthCode` must be a string, and every other field a number that is
+ *   an integer. `null`, a numeric string, a boolean and a fraction return `null`, where Temporal
+ *   would convert or truncate them. A bigint, `NaN` and an infinity return `null` too; Temporal
+ *   throws for them (ToIntegerWithTruncation).
+ *
+ * Range and overflow are left to Temporal. An empty result means nothing is set: the function
+ * returns its value unchanged, where Temporal's `with` would throw. A getter that throws is not
+ * caught here, nor is a Proxy's `getPrototypeOf` trap that throws; the calling function's own catch
+ * returns its sentinel.
+ *
+ * @param fields the caller's `fields` argument
+ * @param allowedFields the fields the calling function takes
+ * @returns a new plain object of the fields set, empty when none is, or null on invalid input
+ *
+ * @example readSetFields({ year: 2025 }, DATE_FIELDS) // { year: 2025 }
+ * @example readSetFields({}, DATE_FIELDS) // {} (nothing set)
+ * @example readSetFields({ year: "2025" }, DATE_FIELDS) // null (not converted)
+ * @example readSetFields({ year: 2025, yaer: 1 }, DATE_FIELDS) // null (misspelt key)
+ * @example readSetFields({ year: 2025, hour: 5 }, DATE_FIELDS) // null (a field setDate does not take)
+ */
+export function readSetFields(fields, allowedFields) {
+    const allowed = allowedFields;
+    if (!isObject(fields) || isTemporalDateOrTimeObject(fields)) {
+        return null;
+    }
+    if (!Object.keys(fields).every((key) => allowed.includes(key))) {
+        return null;
+    }
+    const record = fields;
+    const read = {};
+    for (const name of WITH_PROPERTY_NAMES) {
+        const value = record[name];
+        if (value === undefined) {
+            continue;
+        }
+        if (!allowed.includes(name) || !isFieldValue(name, value)) {
+            return null;
+        }
+        read[name] = value;
+    }
+    return read;
+}

package/dist/internal/resolveDurationRelativeTo.d.ts

@@ -18,6 +18,10 @@ import type { DurationRelativeTo } from "../types/index.js";
  *   calendar must be a `CalendarSystem`, and `"ethiopic"`/`"coptic"` compute in `"ethioaa"`,
  *   which polyfill 0.5.1 can read. The digits are ISO, so this is the date Temporal itself would
  *   read.
+ * - A zoned string without a calendar annotation is read with `zonedDateTimeFrom`, so its offset
+ *   is matched against the zone as TC39 `ToRelativeTemporalObject` matches it: an offset written
+ *   to the minute may be the zone's sub-minute offset rounded, and one written with seconds must
+ *   be the zone's offset exactly (`"1970-01-01T00:00:00-00:45:00[Africa/Monrovia]"` throws).
  * - A leap second (second `60`) throws, in every spelling Temporal's grammar accepts — `T`, `t`
  *   or space separator, extended or basic digits, with or without a designator. Temporal's
  *   ParseISODateTime would otherwise clamp it to `:59`.

package/dist/internal/resolveDurationRelativeTo.js

@@ -3,6 +3,7 @@ import { plainDateTime } from "../regex/date-time.js";
 import { parseCalendarDateValue, temporalStringLeapSecond, } from "./calendarDateString.js";
 import { parseCalendarZonedValue } from "./calendarZonedString.js";
 import { hasZonedDateTimeShape, isoStringBody } from "./isoStringBody.js";
+import { zonedDateTimeFrom } from "./zonedWallClock.js";
 /**
  * A calendar annotation in any spelling: critical flag or not, any letter case. An upper-case key
  * is not Temporal syntax, so it is parsed here and throws rather than reaching Temporal later.
@@ -45,6 +46,10 @@ function hasRelativeToShape(value) {
  *   calendar must be a `CalendarSystem`, and `"ethiopic"`/`"coptic"` compute in `"ethioaa"`,
  *   which polyfill 0.5.1 can read. The digits are ISO, so this is the date Temporal itself would
  *   read.
+ * - A zoned string without a calendar annotation is read with `zonedDateTimeFrom`, so its offset
+ *   is matched against the zone as TC39 `ToRelativeTemporalObject` matches it: an offset written
+ *   to the minute may be the zone's sub-minute offset rounded, and one written with seconds must
+ *   be the zone's offset exactly (`"1970-01-01T00:00:00-00:45:00[Africa/Monrovia]"` throws).
  * - A leap second (second `60`) throws, in every spelling Temporal's grammar accepts — `T`, `t`
  *   or space separator, extended or basic digits, with or without a designator. Temporal's
  *   ParseISODateTime would otherwise clamp it to `:59`.
@@ -70,7 +75,12 @@ export function resolveDurationRelativeTo(relativeTo) {
         throw new RangeError(`Not an extended ISO 8601 date, date-time or zoned date-time: ${relativeTo}`);
     }
     if (!anyCalendarAnnotation.test(relativeTo)) {
-        return relativeTo;
+        // A zoned string is read here, not handed on as text: `zonedDateTimeFrom` matches an offset
+        // written with seconds exactly, as TC39 `ToRelativeTemporalObject` requires and polyfill
+        // 0.5.1 does not (temporalCompat D12).
+        return timeZoneAnnotation.test(relativeTo)
+            ? zonedDateTimeFrom(relativeTo)
+            : relativeTo;
     }
     if (timeZoneAnnotation.test(relativeTo)) {
         return parseCalendarZonedValue(relativeTo);

package/dist/internal/resolveRelativeRounding.d.ts

@@ -3,17 +3,28 @@ import type { RelativeRoundingMethod } from "../types/index.js";
  * Round a relative-time distance to an integer using the given method, defaulting to "round".
  *
  * Applied directly to the signed fractional value (not its absolute value), so floor/ceil
- * respect whether the distance is past (negative) or future (positive) — matches date-fns's
- * `formatDistanceStrict` `roundingMethod` semantics. A rounded `-0` is preserved rather than
- * normalized to `0`: `Intl.RelativeTimeFormat` treats the sign of zero as meaningful (with
- * `numeric: "always"`, `-0` renders as "0 <unit> ago" and `0` as "in 0 <unit>"), so collapsing
- * it here would change existing `formatRelative*` output for near-zero distances.
+ * respect whether the distance is past (negative) or future (positive): "floor" rounds toward
+ * negative infinity and "ceil" toward positive infinity, as ECMA-262 `Math.floor` / `Math.ceil`
+ * and Temporal's rounding modes of the same names do. "round" is ECMA-262 `Math.round`, a half
+ * going toward positive infinity. Comparison: date-fns's `formatDistanceStrict` `roundingMethod`
+ * rounds the unsigned distance, so its floor and ceil differ for a past value.
+ *
+ * A rounded `-0` is preserved rather than normalized to `0`: `Intl.RelativeTimeFormat` treats the
+ * sign of zero as meaningful (with `numeric: "always"`, `-0` renders as "0 <unit> ago" and `0` as
+ * "in 0 <unit>"), so collapsing it here would change existing `formatRelative*` output for
+ * near-zero distances.
+ *
+ * The method is matched against the three names `RelativeRoundingMethod` lists, never looked up on
+ * `Math`: `Math.abs`, `Math.trunc`, `Math.random` and the keys `Math` inherits from
+ * `Object.prototype` are not rounding methods. An `undefined` method is the omitted option
+ * (ECMA-402 `GetOption`, which the Temporal specification also defines) and takes the default.
  *
  * @param value the fractional distance in the target display unit
  * @param method optional: "floor" | "ceil" | "round" (default "round")
- * @returns the rounded amount
+ * @returns the rounded amount; throws RangeError for any other method, for the caller's sentinel
  * @example resolveRelativeRounding(2.7) // 3
  * @example resolveRelativeRounding(2.7, "floor") // 2
  * @example resolveRelativeRounding(-2.7, "ceil") // -2
+ * @example resolveRelativeRounding(-2.7, "abs" as never) // throws RangeError
  */
 export declare function resolveRelativeRounding(value: number, method?: RelativeRoundingMethod): number;

package/dist/internal/resolveRelativeRounding.js

@@ -2,19 +2,39 @@
  * Round a relative-time distance to an integer using the given method, defaulting to "round".
  *
  * Applied directly to the signed fractional value (not its absolute value), so floor/ceil
- * respect whether the distance is past (negative) or future (positive) — matches date-fns's
- * `formatDistanceStrict` `roundingMethod` semantics. A rounded `-0` is preserved rather than
- * normalized to `0`: `Intl.RelativeTimeFormat` treats the sign of zero as meaningful (with
- * `numeric: "always"`, `-0` renders as "0 <unit> ago" and `0` as "in 0 <unit>"), so collapsing
- * it here would change existing `formatRelative*` output for near-zero distances.
+ * respect whether the distance is past (negative) or future (positive): "floor" rounds toward
+ * negative infinity and "ceil" toward positive infinity, as ECMA-262 `Math.floor` / `Math.ceil`
+ * and Temporal's rounding modes of the same names do. "round" is ECMA-262 `Math.round`, a half
+ * going toward positive infinity. Comparison: date-fns's `formatDistanceStrict` `roundingMethod`
+ * rounds the unsigned distance, so its floor and ceil differ for a past value.
+ *
+ * A rounded `-0` is preserved rather than normalized to `0`: `Intl.RelativeTimeFormat` treats the
+ * sign of zero as meaningful (with `numeric: "always"`, `-0` renders as "0 <unit> ago" and `0` as
+ * "in 0 <unit>"), so collapsing it here would change existing `formatRelative*` output for
+ * near-zero distances.
+ *
+ * The method is matched against the three names `RelativeRoundingMethod` lists, never looked up on
+ * `Math`: `Math.abs`, `Math.trunc`, `Math.random` and the keys `Math` inherits from
+ * `Object.prototype` are not rounding methods. An `undefined` method is the omitted option
+ * (ECMA-402 `GetOption`, which the Temporal specification also defines) and takes the default.
  *
  * @param value the fractional distance in the target display unit
  * @param method optional: "floor" | "ceil" | "round" (default "round")
- * @returns the rounded amount
+ * @returns the rounded amount; throws RangeError for any other method, for the caller's sentinel
  * @example resolveRelativeRounding(2.7) // 3
  * @example resolveRelativeRounding(2.7, "floor") // 2
  * @example resolveRelativeRounding(-2.7, "ceil") // -2
+ * @example resolveRelativeRounding(-2.7, "abs" as never) // throws RangeError
  */
 export function resolveRelativeRounding(value, method = "round") {
-    return Math[method](value);
+    switch (method) {
+        case "floor":
+            return Math.floor(value);
+        case "ceil":
+            return Math.ceil(value);
+        case "round":
+            return Math.round(value);
+        default:
+            throw new RangeError(`Invalid roundingMethod: ${String(method)}`);
+    }
 }

package/dist/internal/resolveRelativeUnit.d.ts

@@ -0,0 +1,30 @@
+import type { RelativeUnit } from "../types/index.js";
+/**
+ * Resolve the `largestUnit` option of a `formatRelative*` function to one of the units the
+ * function allows, in its singular form.
+ *
+ * - Temporal reads a unit option with GetTemporalUnitValuedOption, which takes a plural name as
+ *   its singular, then checks it with ValidateTemporalUnitValue against the unit group of the
+ *   type — date, time or datetime — and throws RangeError for a unit outside the group:
+ *   `Temporal.PlainDate.prototype.until` rejects `"hour"`, `Temporal.PlainTime.prototype.until`
+ *   rejects `"day"`. `allowed` is that group for the calling function.
+ * - `undefined` is the omitted option (GetOption), so the caller picks the unit from the distance.
+ * - Unit names are lower case, as in Temporal.
+ * - The set of units is Temporal's. Rejecting a value that is not a string is GMT's own rule, and
+ *   stricter than Temporal: GetOption converts any value with ToString, so Temporal accepts
+ *   `["day"]` and an object whose `toString` returns `"day"` (test262
+ *   `largestunit-wrong-type.js`). GMT takes string inputs, and its other unit readers
+ *   (`roundDate`, `roundDateTime`, `roundUtc`, `roundZoned`, `startOfDate`, `totalDuration`,
+ *   `areDatesEqualBy`) reject a non-string the same way, so this one does not convert either.
+ *
+ * @param largestUnit the option as read from the caller's object, `undefined` when absent
+ * @param allowed the singular units the calling function lists in its type
+ * @returns the singular unit, or `undefined` when the option is absent; throws RangeError for any
+ *   other value, for the caller's sentinel
+ *
+ * @example resolveRelativeUnit("hours", ["hour", "minute", "second"]) // "hour"
+ * @example resolveRelativeUnit(undefined, ["hour", "minute", "second"]) // undefined
+ * @example resolveRelativeUnit("day", ["hour", "minute", "second"]) // throws RangeError
+ * @example resolveRelativeUnit(["hour"], ["hour", "minute", "second"]) // throws RangeError (GMT's rule; Temporal converts it to "hour")
+ */
+export declare function resolveRelativeUnit<Unit extends RelativeUnit>(largestUnit: unknown, allowed: readonly Unit[]): Unit | undefined;

package/dist/internal/resolveRelativeUnit.js

@@ -0,0 +1,40 @@
+/**
+ * Resolve the `largestUnit` option of a `formatRelative*` function to one of the units the
+ * function allows, in its singular form.
+ *
+ * - Temporal reads a unit option with GetTemporalUnitValuedOption, which takes a plural name as
+ *   its singular, then checks it with ValidateTemporalUnitValue against the unit group of the
+ *   type — date, time or datetime — and throws RangeError for a unit outside the group:
+ *   `Temporal.PlainDate.prototype.until` rejects `"hour"`, `Temporal.PlainTime.prototype.until`
+ *   rejects `"day"`. `allowed` is that group for the calling function.
+ * - `undefined` is the omitted option (GetOption), so the caller picks the unit from the distance.
+ * - Unit names are lower case, as in Temporal.
+ * - The set of units is Temporal's. Rejecting a value that is not a string is GMT's own rule, and
+ *   stricter than Temporal: GetOption converts any value with ToString, so Temporal accepts
+ *   `["day"]` and an object whose `toString` returns `"day"` (test262
+ *   `largestunit-wrong-type.js`). GMT takes string inputs, and its other unit readers
+ *   (`roundDate`, `roundDateTime`, `roundUtc`, `roundZoned`, `startOfDate`, `totalDuration`,
+ *   `areDatesEqualBy`) reject a non-string the same way, so this one does not convert either.
+ *
+ * @param largestUnit the option as read from the caller's object, `undefined` when absent
+ * @param allowed the singular units the calling function lists in its type
+ * @returns the singular unit, or `undefined` when the option is absent; throws RangeError for any
+ *   other value, for the caller's sentinel
+ *
+ * @example resolveRelativeUnit("hours", ["hour", "minute", "second"]) // "hour"
+ * @example resolveRelativeUnit(undefined, ["hour", "minute", "second"]) // undefined
+ * @example resolveRelativeUnit("day", ["hour", "minute", "second"]) // throws RangeError
+ * @example resolveRelativeUnit(["hour"], ["hour", "minute", "second"]) // throws RangeError (GMT's rule; Temporal converts it to "hour")
+ */
+export function resolveRelativeUnit(largestUnit, allowed) {
+    if (largestUnit === undefined) {
+        return undefined;
+    }
+    const unit = typeof largestUnit === "string"
+        ? allowed.find((name) => name === largestUnit || `${name}s` === largestUnit)
+        : undefined;
+    if (unit === undefined) {
+        throw new RangeError(`Invalid largestUnit: ${String(largestUnit)}`);
+    }
+    return unit;
+}

package/dist/internal/resolveUnixIntervalPair.d.ts

@@ -1,10 +1,13 @@
 import type { Temporal } from "@js-temporal/polyfill";
 import { type UnixEpochUnit } from "./unixEpochValue.js";
+import { type ZoneFrame } from "./zoneFrame.js";
 export interface ResolvedUnixInterval {
     startVal: Temporal.ZonedDateTime;
     endVal: Temporal.ZonedDateTime;
     resolvedUnit: Temporal.DateTimeUnit;
     epochUnit: UnixEpochUnit;
+    /** The frame both ends were placed on; `frameInstant` turns a result back into an instant. */
+    frame: ZoneFrame;
 }
 /**
  * Resolve the shared arguments of `intervalLengthUnix`, `intervalCountUnix` and
@@ -13,13 +16,16 @@ export interface ResolvedUnixInterval {
  *
  * - Epochs follow the one `unix/` grammar (`parseUnixEpochValue`) and must name Temporal instants.
  * - `epochUnit` defaults to `"milliseconds"`; `timeZone` defaults to `"UTC"` (`"local"` is the
- *   system zone, an unknown zone is invalid).
+ *   system zone; a time zone identifier or a stored UTC offset `±HH:MM[:SS]` is read as written;
+ *   anything else is invalid).
+ * - The ends are placed with `frameZoned`: for a seconds offset they sit in the offset's
+ *   whole-minute zone, moved by its seconds, to compute with and never to write.
  *
  * @param start interval start epoch
  * @param end interval end epoch
  * @param unit unit name, singular or plural
  * @param options optional `{ epochUnit, timeZone }`
- * @returns the zoned ends, singular unit and epoch unit, or null on invalid input
+ * @returns the zoned ends, singular unit, epoch unit and frame, or null on invalid input
  *
  * @example resolveUnixIntervalPair(0, 86400, "days", { epochUnit: "seconds" })?.resolvedUnit // "day"
  * @example resolveUnixIntervalPair(10, 0, "day") // null (reversed)

package/dist/internal/resolveUnixIntervalPair.js

@@ -1,7 +1,7 @@
-import { normalizeTimeZone } from "./normalizeTimeZone.js";
 import { resolveDateTimeUnit } from "./resolveDateTimeUnit.js";
 import { parseUnixEpochInterval, resolveUnixEpochUnit, unixEpochToInstant, } from "./unixEpochValue.js";
 import { isValidDateTimeUnit } from "../plain/validate/index.js";
+import { frameZoned, normalizeZoneFrame } from "./zoneFrame.js";
 /**
  * Resolve the shared arguments of `intervalLengthUnix`, `intervalCountUnix` and
  * `splitIntervalByUnitUnix`: a non-reversed epoch pair in `epochUnit`, a singular-or-plural
@@ -9,13 +9,16 @@ import { isValidDateTimeUnit } from "../plain/validate/index.js";
  *
  * - Epochs follow the one `unix/` grammar (`parseUnixEpochValue`) and must name Temporal instants.
  * - `epochUnit` defaults to `"milliseconds"`; `timeZone` defaults to `"UTC"` (`"local"` is the
- *   system zone, an unknown zone is invalid).
+ *   system zone; a time zone identifier or a stored UTC offset `±HH:MM[:SS]` is read as written;
+ *   anything else is invalid).
+ * - The ends are placed with `frameZoned`: for a seconds offset they sit in the offset's
+ *   whole-minute zone, moved by its seconds, to compute with and never to write.
  *
  * @param start interval start epoch
  * @param end interval end epoch
  * @param unit unit name, singular or plural
  * @param options optional `{ epochUnit, timeZone }`
- * @returns the zoned ends, singular unit and epoch unit, or null on invalid input
+ * @returns the zoned ends, singular unit, epoch unit and frame, or null on invalid input
  *
  * @example resolveUnixIntervalPair(0, 86400, "days", { epochUnit: "seconds" })?.resolvedUnit // "day"
  * @example resolveUnixIntervalPair(10, 0, "day") // null (reversed)
@@ -23,10 +26,10 @@ import { isValidDateTimeUnit } from "../plain/validate/index.js";
 export function resolveUnixIntervalPair(start, end, unit, options) {
     const interval = parseUnixEpochInterval(start, end);
     const epochUnit = resolveUnixEpochUnit(options?.epochUnit);
-    const timeZone = normalizeTimeZone(options?.timeZone);
+    const frame = normalizeZoneFrame(options?.timeZone);
     if (interval === null ||
         epochUnit === null ||
-        !timeZone ||
+        frame === null ||
         typeof unit !== "string") {
         return null;
     }
@@ -41,10 +44,11 @@ export function resolveUnixIntervalPair(start, end, unit, options) {
     }
     try {
         return {
-            startVal: startInstant.toZonedDateTimeISO(timeZone),
-            endVal: endInstant.toZonedDateTimeISO(timeZone),
+            startVal: frameZoned(startInstant, frame),
+            endVal: frameZoned(endInstant, frame),
             resolvedUnit,
             epochUnit,
+            frame,
         };
     }
     catch {

package/dist/internal/splitStep.d.ts

@@ -33,7 +33,8 @@ export declare function isExactDurationUnit(unit: string): boolean;
  * - A step that goes backwards returns `null`.
  * - More than `maxSlices` slices returns `null` as soon as the next one is due, so the work stays
  *   bounded by the limit (owner decision A2, CORE-8).
- * - The last slice's end is trimmed to `end`. Callers handle `start >= end` before calling.
+ * - The last slice's end is `end` itself, whether the last step passes `end` (trimmed) or lands on
+ *   it. Callers handle `start >= end` before calling.
  * - A step that throws a RangeError (it lands past Temporal's last representable value, so after
  *   `end`) closes the split with a last slice ending at `end`.
  *
@@ -57,6 +58,28 @@ export declare function isExactDurationUnit(unit: string): boolean;
 export declare function tileByUnit<T extends {
     add(duration: Temporal.DurationLike): T;
 }>(start: T, end: T, compare: (a: T, b: T) => number, unit: string, amount: number, maxSlices: number, add?: (value: T, duration: Temporal.DurationLike) => T): Array<[T, T]> | null;
+/**
+ * The step a split takes when its boundaries are then floored to whole `floorUnit`s.
+ *
+ * - An exact step shorter than one `floorUnit` moves each boundary by less than one unit, so the
+ *   floored boundaries are every whole unit from the start to the end, each one repeated once per
+ *   step that falls inside it. Stepping by one `floorUnit` gives those boundaries once each: no
+ *   empty piece, and no work spent on steps the result cannot show.
+ * - Any other step is returned unchanged: a step of one `floorUnit` or more never floors two
+ *   boundaries to the same value, a calendar step is never shorter than a second, and a
+ *   fractional `amount` is left for Temporal to reject.
+ * - The split's start must itself be a whole `floorUnit`, as a Unix epoch is.
+ *
+ * @param unit plural duration unit, as returned by `resolveDurationUnit`
+ * @param amount positive number of units per step
+ * @param floorUnit plural exact unit the boundaries are floored to
+ * @returns the `[unit, amount]` to step by
+ *
+ * @example stepNoFinerThan("milliseconds", 500, "seconds") // ["seconds", 1]
+ * @example stepNoFinerThan("milliseconds", 1500, "seconds") // ["milliseconds", 1500]
+ * @example stepNoFinerThan("days", 1, "seconds") // ["days", 1]
+ */
+export declare function stepNoFinerThan(unit: string, amount: number, floorUnit: string): [unit: string, amount: number];
 /**
  * A lower bound on the number of slices `tileByUnit` returns for a span, without stepping.
  *

package/dist/internal/splitStep.js

@@ -68,7 +68,8 @@ function closedAtRangeLimit(slices, current, end, maxSlices) {
  * - A step that goes backwards returns `null`.
  * - More than `maxSlices` slices returns `null` as soon as the next one is due, so the work stays
  *   bounded by the limit (owner decision A2, CORE-8).
- * - The last slice's end is trimmed to `end`. Callers handle `start >= end` before calling.
+ * - The last slice's end is `end` itself, whether the last step passes `end` (trimmed) or lands on
+ *   it. Callers handle `start >= end` before calling.
  * - A step that throws a RangeError (it lands past Temporal's last representable value, so after
  *   `end`) closes the split with a last slice ending at `end`.
  *
@@ -111,7 +112,9 @@ export function tileByUnit(start, end, compare, unit, amount, maxSlices, add = (
             return null;
         }
         stalled = 0;
-        slices.push([current, compare(next, end) > 0 ? end : next]);
+        // A step that lands on `end` closes with `end` itself, as a trimmed one does: the two compare
+        // equal but may be written differently (a zoned `end` in another zone than `start`).
+        slices.push([current, compare(next, end) >= 0 ? end : next]);
         current = next;
     }
     return slices;
@@ -135,6 +138,35 @@ const LONGEST_UNIT_NANOSECONDS = {
     months: 31 * NANOSECONDS_PER_DAY,
     years: 385 * NANOSECONDS_PER_DAY,
 };
+/**
+ * The step a split takes when its boundaries are then floored to whole `floorUnit`s.
+ *
+ * - An exact step shorter than one `floorUnit` moves each boundary by less than one unit, so the
+ *   floored boundaries are every whole unit from the start to the end, each one repeated once per
+ *   step that falls inside it. Stepping by one `floorUnit` gives those boundaries once each: no
+ *   empty piece, and no work spent on steps the result cannot show.
+ * - Any other step is returned unchanged: a step of one `floorUnit` or more never floors two
+ *   boundaries to the same value, a calendar step is never shorter than a second, and a
+ *   fractional `amount` is left for Temporal to reject.
+ * - The split's start must itself be a whole `floorUnit`, as a Unix epoch is.
+ *
+ * @param unit plural duration unit, as returned by `resolveDurationUnit`
+ * @param amount positive number of units per step
+ * @param floorUnit plural exact unit the boundaries are floored to
+ * @returns the `[unit, amount]` to step by
+ *
+ * @example stepNoFinerThan("milliseconds", 500, "seconds") // ["seconds", 1]
+ * @example stepNoFinerThan("milliseconds", 1500, "seconds") // ["milliseconds", 1500]
+ * @example stepNoFinerThan("days", 1, "seconds") // ["days", 1]
+ */
+export function stepNoFinerThan(unit, amount, floorUnit) {
+    const isFiner = isExactDurationUnit(unit) &&
+        isExactDurationUnit(floorUnit) &&
+        Number.isInteger(amount) &&
+        LONGEST_UNIT_NANOSECONDS[unit] * amount <
+            LONGEST_UNIT_NANOSECONDS[floorUnit];
+    return isFiner ? [floorUnit, 1] : [unit, amount];
+}
 /**
  * A zoned boundary can sit this far from its wall-clock distance: a UTC offset lies strictly
  * within ±24 hours (Temporal IsOffsetTimeZoneIdentifier / ECMA-262 time zone offset range), so

package/dist/internal/startOrEndOfUnix.d.ts

@@ -8,7 +8,8 @@ import type { Temporal } from "@js-temporal/polyfill";
  *   or `"quarter"` from `startOfQuarterForUnix` / `endOfQuarterForUnix` only.
  * - `value` follows the one epoch grammar (`parseUnixEpochValue`); `epochUnit` accepts singular
  *   and plural names and defaults to `"milliseconds"`.
- * - `timeZone` defaults to `"UTC"`; `"local"` is the system zone; an unknown zone returns null.
+ * - `timeZone` defaults to `"UTC"`; `"local"` is the system zone; a time zone identifier or a
+ *   stored UTC offset (`±HH:MM[:SS]`) is read as written; anything else returns null.
  * - `weekStartsOn` other than `"monday"` or `"sunday"` returns null.
  * - The boundary is always the real local bucket from `internal/zonedBucket.ts` — a start never
  *   after `value`, an end never before it.

package/dist/internal/startOrEndOfUnix.js

@@ -1,7 +1,7 @@
-import { normalizeTimeZone } from "./normalizeTimeZone.js";
 import { resolveWeekStartsOn } from "./resolveWeekStartsOn.js";
 import { resolveUnixEpochUnit, toUnixEpoch, unixEpochToInstant, } from "./unixEpochValue.js";
 import { zonedUnitEnd, zonedUnitStart } from "./zonedBucket.js";
+import { frameInstant, frameZoned, normalizeZoneFrame } from "./zoneFrame.js";
 /**
  * Internal shared implementation for `startOfUnix` / `endOfUnix` and the quarter functions.
  *
@@ -11,7 +11,8 @@ import { zonedUnitEnd, zonedUnitStart } from "./zonedBucket.js";
  *   or `"quarter"` from `startOfQuarterForUnix` / `endOfQuarterForUnix` only.
  * - `value` follows the one epoch grammar (`parseUnixEpochValue`); `epochUnit` accepts singular
  *   and plural names and defaults to `"milliseconds"`.
- * - `timeZone` defaults to `"UTC"`; `"local"` is the system zone; an unknown zone returns null.
+ * - `timeZone` defaults to `"UTC"`; `"local"` is the system zone; a time zone identifier or a
+ *   stored UTC offset (`±HH:MM[:SS]`) is read as written; anything else returns null.
  * - `weekStartsOn` other than `"monday"` or `"sunday"` returns null.
  * - The boundary is always the real local bucket from `internal/zonedBucket.ts` — a start never
  *   after `value`, an end never before it.
@@ -24,9 +25,9 @@ import { zonedUnitEnd, zonedUnitStart } from "./zonedBucket.js";
  */
 export function startOrEndOfUnix(value, unit, options, isEnd) {
     const epochUnit = resolveUnixEpochUnit(options.epochUnit);
-    const timeZone = normalizeTimeZone(options.timeZone);
+    const frame = normalizeZoneFrame(options.timeZone);
     const weekStartsOn = resolveWeekStartsOn(options.weekStartsOn);
-    if (!timeZone || epochUnit === null || weekStartsOn === null) {
+    if (frame === null || epochUnit === null || weekStartsOn === null) {
         return null;
     }
     const instant = unixEpochToInstant(value, epochUnit);
@@ -35,11 +36,13 @@ export function startOrEndOfUnix(value, unit, options, isEnd) {
     }
     const weekStartDay = weekStartsOn === "monday" ? 1 : 7;
     try {
-        const source = instant.toZonedDateTimeISO(timeZone);
+        const source = frameZoned(instant, frame);
         const boundary = isEnd
             ? zonedUnitEnd(source, unit, weekStartDay)
             : zonedUnitStart(source, unit, weekStartDay);
-        return boundary ? toUnixEpoch(boundary, epochUnit) : null;
+        return boundary
+            ? toUnixEpoch(frameInstant(boundary, frame), epochUnit)
+            : null;
     }
     catch {
         return null;

package/dist/internal/startOrEndOfZoned.js

@@ -5,6 +5,7 @@ import { resolveDateTimeUnit } from "./resolveDateTimeUnit.js";
 import { resolveWeekStartsOn } from "./resolveWeekStartsOn.js";
 import { isValidDateTimeUnit } from "../plain/validate/index.js";
 import { isValidZonedDateTime } from "../zoned/validate/index.js";
+import { optionOrDefault } from "./optionOrDefault.js";
 /**
  * Internal shared implementation for `startOfZoned` / `endOfZoned`.
  *
@@ -32,9 +33,7 @@ export function startOrEndOfZoned(value, unit, options, isEnd) {
     // An end is next start − 1 ns, so it defaults to nanosecond precision: fewer digits would
     // print an earlier instant than the end (Calendar & zone semantics §3).
     const fractionalSecondDigits = isEnd
-        ? options.fractionalSecondDigits === undefined
-            ? 9
-            : options.fractionalSecondDigits
+        ? optionOrDefault(options.fractionalSecondDigits, 9)
         : defaultFractionalDigits(resolvedUnit, options.fractionalSecondDigits);
     try {
         const source = zonedDateTimeFrom(value);