@northguild/gmt 1.16.0 → 1.18.0

package/dist/internal/optionOrDefault.js

@@ -0,0 +1,20 @@
+/**
+ * The value of an option that was read once, or its default when the option is absent.
+ *
+ * - ECMA-402 `GetOption` (the Temporal specification defines the same operation) reads the
+ *   property with one `Get` and returns the default only when that value is `undefined`. Pass
+ *   the property read as the argument, so the option is read exactly once: a getter cannot
+ *   answer one value to the check and another to the use.
+ * - `null` is a value, not an omission, so it is returned as it is for the caller to validate.
+ *
+ * @param value the option as read from the caller's object, `undefined` when absent
+ * @param fallback the documented default
+ * @returns `fallback` when `value` is `undefined`, otherwise `value`
+ *
+ * @example optionOrDefault(undefined, "compatible") // "compatible"
+ * @example optionOrDefault("later", "compatible") // "later"
+ * @example optionOrDefault(null, true) // null (a value for the caller to validate)
+ */
+export function optionOrDefault(value, fallback) {
+    return value === undefined ? fallback : value;
+}

package/dist/internal/patternToken.d.ts

@@ -3,8 +3,8 @@ import { type LocalesArgument } from "./resolveLocale.js";
  * Shared token-pattern engine for J11's `parse*WithPattern` family.
  *
  * This is GMT's one named exception to `context/coding-standards.md`'s
- * "manual string parsing" prohibition (Decision 4 in
- * `context/roadmap/issues/J.md`). The exception is scoped to this module
+ * "manual string parsing" prohibition (its section "Scoped exception:
+ * manual string parsing"). The exception is scoped to this module
  * and the three `parse*WithPattern` public functions, and is bound by
  * three rules, enforced throughout this file:
  *   1. The regex is always built *from the pattern string itself* at call

package/dist/internal/patternToken.js

@@ -24,9 +24,10 @@ export const DATE_TIME_PATTERN_FIELDS = new Set([
     ...DATE_PATTERN_FIELDS,
     ...TIME_PATTERN_FIELDS,
 ]);
-// Recognized vocabulary letters (Decision 1's Luxon-derived token set,
-// restricted to what's unambiguous to parse — no offset/zone-name tokens
-// since this story is plain-only). Any other unquoted letter in a pattern
+// Recognized vocabulary letters: a subset of the UTS #35 Date Field Symbol
+// Table, with its field lengths (`MMM` abbreviated, `MMMM` wide), restricted
+// to what's unambiguous to parse — no offset/zone-name tokens since this
+// story is plain-only (Decision 1). Any other unquoted letter in a pattern
 // is malformed. Numeric ranges are baked into each regex so a shape
 // mismatch (e.g. "13" for a 12-hour token) fails at the regex stage,
 // before ever reaching Temporal.
@@ -78,13 +79,21 @@ const VOCABULARY_LETTERS = "yMdHhmsSEaG";
 /**
  * Split a pattern string into literal and letter-run parts.
  *
- * Quoted segments (`'...'`) are literals matched verbatim; a doubled `''`
- * *inside* an open quote is the escape for one literal `'` character
- * (mirrors Luxon's own escaping exactly — Decision 1 already establishes
- * Luxon's vocabulary as this story's starting point). Any character that
- * isn't part of a letter run and isn't inside a quote (separators,
- * literal digits, punctuation) is automatically a one-character literal —
- * no explicit quoting required for those.
+ * Literal text follows UTS #35 Part 4, Date Format Patterns
+ * (https://unicode.org/reports/tr35/tr35-dates.html#Date_Format_Patterns):
+ *   - "Any characters other than A..Z and a..z, including spaces and
+ *     punctuation" are literals with no quoting.
+ *   - "Any text between single vertical quotes ('xxxx'), which may include
+ *     A..Z and a..z as literal text."
+ *   - "Two adjacent single vertical quotes (''), which represent a literal
+ *     single quote, either inside or outside quoted text."
+ *
+ * The pattern is read left to right, so a `''` pair is taken before a
+ * lone `'` is read as opening or closing quoted text: `''''` is two
+ * literal quotes, and `'''T'` is a literal quote followed by the quoted
+ * text `T`. UTS #35 defines quoted text only as text *between* two
+ * quotes, so a quote that never closes has no defined meaning and the
+ * pattern is malformed (`null`).
  */
 function tokenizePattern(pattern) {
     const parts = [];
@@ -92,6 +101,12 @@ function tokenizePattern(pattern) {
     while (i < pattern.length) {
         const ch = pattern[i];
         if (ch === "'") {
+            // `''` outside quoted text: one literal quote, no quoted text opened.
+            if (pattern[i + 1] === "'") {
+                parts.push({ type: "literal", text: "'" });
+                i += 2;
+                continue;
+            }
             let j = i + 1;
             let text = "";
             let closed = false;
@@ -109,9 +124,9 @@ function tokenizePattern(pattern) {
                 text += pattern[j];
                 j += 1;
             }
-            // An unterminated quote has no unambiguous literal meaning — treat
-            // it as a malformed pattern rather than guessing where it "should"
-            // have closed.
+            // UTS #35 gives quoted text a meaning only between two quotes, so
+            // an unterminated quote is a malformed pattern, not a guess at
+            // where it should have closed.
             if (!closed)
                 return null;
             parts.push({ type: "literal", text });

package/dist/internal/plainDateUntil.js

@@ -24,16 +24,20 @@ function singularDateUnit(unit) {
  * @example plainDateUntil(Temporal.PlainDate.from("2024-01-31"), Temporal.PlainDate.from("2024-03-01"), "months").toString() // "P1M1D"
  */
 export function plainDateUntil(start, end, largestUnit, options) {
-    if (options?.smallestUnit === undefined &&
-        options?.roundingIncrement === undefined &&
-        options?.roundingMode === undefined) {
+    // Each option is read once (GetOption).
+    const smallestUnit = options?.smallestUnit;
+    const roundingIncrement = options?.roundingIncrement;
+    const roundingMode = options?.roundingMode;
+    if (smallestUnit === undefined &&
+        roundingIncrement === undefined &&
+        roundingMode === undefined) {
         return Temporal.Duration.from(calendarDateUntil(start, end, singularDateUnit(largestUnit)));
     }
     const untilOptions = {
         largestUnit: largestUnit,
-        smallestUnit: options.smallestUnit,
-        roundingIncrement: options.roundingIncrement,
-        roundingMode: options.roundingMode,
+        smallestUnit,
+        roundingIncrement,
+        roundingMode,
     };
     // No D11 term here. The nudge window can only miss its target when the target sits strictly
     // between the window bounds by a sub-day amount, which is why every D11 case carries a time

package/dist/internal/punctuality.d.ts

@@ -0,0 +1,38 @@
+import type { Punctuality } from "../types/index.js";
+/** A `PunctualityTolerance` as non-negative exact nanoseconds; `early` is `null` when absent. */
+export type ToleranceNanoseconds = {
+    late: bigint;
+    early: bigint | null;
+};
+/**
+ * Read a `PunctualityTolerance` once into exact nanoseconds, or `null` when it is invalid.
+ *
+ * - `late` and `early` are each read exactly once, so a caller that classifies many pairs under
+ *   one tolerance really uses one tolerance, whatever a getter returns on a later read.
+ * - Each bound is an exact duration (a day is 24 hours; years, months and weeks refused) and not
+ *   negative (`-PT0S` is zero). `late` is required; `early: undefined` is absent and
+ *   `early: null` is invalid.
+ * - A hostile value (a throwing getter, a revoked Proxy) is invalid input: `null`, never a throw.
+ *
+ * @param tolerance candidate `{ late, early? }`
+ * @returns the bounds in nanoseconds, or null on invalid input
+ *
+ * @example parsePunctualityTolerance({ late: "PT15M" }) // { late: 900000000000n, early: null }
+ * @example parsePunctualityTolerance({ late: "-PT15M" }) // null
+ */
+export declare function parsePunctualityTolerance(tolerance: unknown): ToleranceNanoseconds | null;
+/**
+ * Classify a deviation (actual − planned, exact nanoseconds) against a tolerance.
+ *
+ * Late when the deviation is `late` or more; early when `early` is set and the deviation is
+ * `-early` or less; on time strictly between. Late is checked first, so with both bounds zero the
+ * plan itself is late.
+ *
+ * @param deviation actual minus planned, in nanoseconds
+ * @param tolerance the bounds from `parsePunctualityTolerance`
+ * @returns "early", "onTime" or "late"
+ *
+ * @example punctualityOf(900000000000n, { late: 900000000000n, early: null }) // "late"
+ * @example punctualityOf(0n, { late: 900000000000n, early: 0n }) // "early"
+ */
+export declare function punctualityOf(deviation: bigint, tolerance: ToleranceNanoseconds): Punctuality;

package/dist/internal/punctuality.js

@@ -0,0 +1,59 @@
+import { nonNegativeExactDurationNanoseconds } from "./exactDuration.js";
+import { isObject } from "./isObject.js";
+/**
+ * Read a `PunctualityTolerance` once into exact nanoseconds, or `null` when it is invalid.
+ *
+ * - `late` and `early` are each read exactly once, so a caller that classifies many pairs under
+ *   one tolerance really uses one tolerance, whatever a getter returns on a later read.
+ * - Each bound is an exact duration (a day is 24 hours; years, months and weeks refused) and not
+ *   negative (`-PT0S` is zero). `late` is required; `early: undefined` is absent and
+ *   `early: null` is invalid.
+ * - A hostile value (a throwing getter, a revoked Proxy) is invalid input: `null`, never a throw.
+ *
+ * @param tolerance candidate `{ late, early? }`
+ * @returns the bounds in nanoseconds, or null on invalid input
+ *
+ * @example parsePunctualityTolerance({ late: "PT15M" }) // { late: 900000000000n, early: null }
+ * @example parsePunctualityTolerance({ late: "-PT15M" }) // null
+ */
+export function parsePunctualityTolerance(tolerance) {
+    try {
+        if (!isObject(tolerance)) {
+            return null;
+        }
+        const { late, early } = tolerance;
+        const lateNanoseconds = nonNegativeExactDurationNanoseconds(late);
+        const earlyNanoseconds = early === undefined ? null : nonNegativeExactDurationNanoseconds(early);
+        if (lateNanoseconds === null ||
+            (early !== undefined && earlyNanoseconds === null)) {
+            return null;
+        }
+        return { late: lateNanoseconds, early: earlyNanoseconds };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Classify a deviation (actual − planned, exact nanoseconds) against a tolerance.
+ *
+ * Late when the deviation is `late` or more; early when `early` is set and the deviation is
+ * `-early` or less; on time strictly between. Late is checked first, so with both bounds zero the
+ * plan itself is late.
+ *
+ * @param deviation actual minus planned, in nanoseconds
+ * @param tolerance the bounds from `parsePunctualityTolerance`
+ * @returns "early", "onTime" or "late"
+ *
+ * @example punctualityOf(900000000000n, { late: 900000000000n, early: null }) // "late"
+ * @example punctualityOf(0n, { late: 900000000000n, early: 0n }) // "early"
+ */
+export function punctualityOf(deviation, tolerance) {
+    if (deviation >= tolerance.late) {
+        return "late";
+    }
+    if (tolerance.early !== null && deviation <= -tolerance.early) {
+        return "early";
+    }
+    return "onTime";
+}

package/dist/internal/readDateTimeFormatOptions.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Read a caller's `Intl.DateTimeFormat` options once, into a plain object of primitives.
+ *
+ * - A formatter that inspects the options before it hands them to `Intl.DateTimeFormat` would
+ *   otherwise read each one several times, and a getter could answer one value to the check and
+ *   another to the formatter. ECMA-402 CreateDateTimeFormat reads each option with one `Get`
+ *   (GetOption); this does the same, in the same order, and everything after works on the copy.
+ * - Each value is converted once as well, right after its `Get`, as GetOption converts it:
+ *   ToString for a string option, ToNumber for `fractionalSecondDigits`, ToBoolean for `hour12`.
+ *   An option given as an object would otherwise be asked for its value by every
+ *   `Intl.DateTimeFormat` built from the copy, and could answer each one differently. The range
+ *   and the allowed values are still checked by `Intl.DateTimeFormat`. `timeZone` alone is copied
+ *   unconverted, for the caller's own zone rule.
+ * - The object is coerced as ECMA-402 CoerceOptionsToObject coerces it: `undefined` is no options,
+ *   `null` throws TypeError, and a string or a number has none of these properties. Inherited
+ *   properties are read, as `Get` reads them.
+ * - Only the options `Intl.DateTimeFormat` reads are copied, and only those that are not
+ *   `undefined`. Any other key was never read by the formatter, so dropping it changes nothing.
+ *
+ * @param options the caller's options argument
+ * @returns a plain object holding each option that was set, converted to its primitive; throws
+ *   TypeError for `null`, or for a value that cannot be converted, for the caller's sentinel
+ *
+ * @example readDateTimeFormatOptions({ dateStyle: "long", extra: 1 }) // { dateStyle: "long" }
+ * @example readDateTimeFormatOptions({ month: { toString: () => "long" } }) // { month: "long" }
+ * @example readDateTimeFormatOptions(undefined) // {}
+ * @example readDateTimeFormatOptions("x") // {} (a string has no date-time options)
+ * @example readDateTimeFormatOptions(null) // throws TypeError
+ */
+export declare function readDateTimeFormatOptions(options: unknown): Intl.DateTimeFormatOptions;

package/dist/internal/readDateTimeFormatOptions.js

@@ -0,0 +1,93 @@
+/**
+ * The options ECMA-402 CreateDateTimeFormat reads, in the order it reads them: the formatter's own
+ * settings, then `timeZone`, then each date-time component, then `formatMatcher` and the styles.
+ */
+const DATE_TIME_FORMAT_OPTIONS = [
+    "localeMatcher",
+    "calendar",
+    "numberingSystem",
+    "hour12",
+    "hourCycle",
+    "timeZone",
+    "weekday",
+    "era",
+    "year",
+    "month",
+    "day",
+    "dayPeriod",
+    "hour",
+    "minute",
+    "second",
+    "fractionalSecondDigits",
+    "timeZoneName",
+    "formatMatcher",
+    "dateStyle",
+    "timeStyle",
+];
+/**
+ * Convert an option's value as ECMA-402 GetOption converts it for that option's type: ToBoolean
+ * for `hour12`, ToNumber for `fractionalSecondDigits` (GetNumberOption), ToString for every other
+ * option. `timeZone` is the exception and is returned as it was read: each caller has its own
+ * rule for a zone, and one that hands it to `Intl.DateTimeFormat` does so once.
+ *
+ * The template literal and the unary plus are ToString and ToNumber exactly, so a symbol (and a
+ * bigint for a number) throws TypeError as it does inside `Intl.DateTimeFormat`.
+ */
+function convertOption(name, value) {
+    switch (name) {
+        case "timeZone":
+            return value;
+        case "hour12":
+            return Boolean(value);
+        case "fractionalSecondDigits":
+            return +value;
+        default:
+            return `${value}`;
+    }
+}
+/**
+ * Read a caller's `Intl.DateTimeFormat` options once, into a plain object of primitives.
+ *
+ * - A formatter that inspects the options before it hands them to `Intl.DateTimeFormat` would
+ *   otherwise read each one several times, and a getter could answer one value to the check and
+ *   another to the formatter. ECMA-402 CreateDateTimeFormat reads each option with one `Get`
+ *   (GetOption); this does the same, in the same order, and everything after works on the copy.
+ * - Each value is converted once as well, right after its `Get`, as GetOption converts it:
+ *   ToString for a string option, ToNumber for `fractionalSecondDigits`, ToBoolean for `hour12`.
+ *   An option given as an object would otherwise be asked for its value by every
+ *   `Intl.DateTimeFormat` built from the copy, and could answer each one differently. The range
+ *   and the allowed values are still checked by `Intl.DateTimeFormat`. `timeZone` alone is copied
+ *   unconverted, for the caller's own zone rule.
+ * - The object is coerced as ECMA-402 CoerceOptionsToObject coerces it: `undefined` is no options,
+ *   `null` throws TypeError, and a string or a number has none of these properties. Inherited
+ *   properties are read, as `Get` reads them.
+ * - Only the options `Intl.DateTimeFormat` reads are copied, and only those that are not
+ *   `undefined`. Any other key was never read by the formatter, so dropping it changes nothing.
+ *
+ * @param options the caller's options argument
+ * @returns a plain object holding each option that was set, converted to its primitive; throws
+ *   TypeError for `null`, or for a value that cannot be converted, for the caller's sentinel
+ *
+ * @example readDateTimeFormatOptions({ dateStyle: "long", extra: 1 }) // { dateStyle: "long" }
+ * @example readDateTimeFormatOptions({ month: { toString: () => "long" } }) // { month: "long" }
+ * @example readDateTimeFormatOptions(undefined) // {}
+ * @example readDateTimeFormatOptions("x") // {} (a string has no date-time options)
+ * @example readDateTimeFormatOptions(null) // throws TypeError
+ */
+export function readDateTimeFormatOptions(options) {
+    if (options === null) {
+        throw new TypeError("options must be an object or undefined");
+    }
+    const read = {};
+    if (options === undefined) {
+        return read;
+    }
+    const source = Object(options);
+    for (const name of DATE_TIME_FORMAT_OPTIONS) {
+        const value = source[name];
+        if (value !== undefined) {
+            read[name] = convertOption(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`, `durationAs`,
+ *   `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`, `durationAs`,
+ *   `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/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.
  *