@northguild/gmt 1.15.0 → 1.17.0

package/dist/internal/plainDateUntil.d.ts

@@ -0,0 +1,21 @@
+import { Temporal } from "@js-temporal/polyfill";
+import type { RoundingOptions } from "../types/index.js";
+/**
+ * `start.until(end, { largestUnit, ...rounding })` for two PlainDates in the same calendar.
+ *
+ * - Without rounding options the difference goes through the Temporal compat layer's
+ *   `calendarDateUntil`, which is the polyfill's own `until` for `iso8601` and the TC39
+ *   `NonISODateUntil` answer for other calendars (CORE-6 D1, D6, D7 and the corrected calendars).
+ * - With `smallestUnit`, `roundingIncrement` or `roundingMode`, a calendar whose compat is needed
+ *   goes through `plainDateUntilWithRounding` (TC39 `DifferenceTemporalPlainDate` in the plain
+ *   context, `GetUTCEpochNanoseconds`); every other calendar is the polyfill's own `until`.
+ *
+ * @param start PlainDate the difference starts from
+ * @param end PlainDate in the same calendar
+ * @param largestUnit a date unit, singular or plural
+ * @param options optional DifferenceOptions rounding controls
+ * @returns the difference as a Temporal.Duration; throws RangeError on invalid input
+ *
+ * @example plainDateUntil(Temporal.PlainDate.from("2024-01-31"), Temporal.PlainDate.from("2024-03-01"), "months").toString() // "P1M1D"
+ */
+export declare function plainDateUntil(start: Temporal.PlainDate, end: Temporal.PlainDate, largestUnit: string, options?: RoundingOptions<Temporal.DateUnit>): Temporal.Duration;

package/dist/internal/plainDateUntil.js

@@ -0,0 +1,48 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { calendarDateUntil, isCalendarArithmeticCompatNeeded, } from "./temporalCompat/index.js";
+import { plainDateUntilWithRounding } from "./zonedWallClockDifference.js";
+/** Plural date units to Temporal's singular spelling; anything else passes through unchanged. */
+function singularDateUnit(unit) {
+    return (unit.endsWith("s") ? unit.slice(0, -1) : unit);
+}
+/**
+ * `start.until(end, { largestUnit, ...rounding })` for two PlainDates in the same calendar.
+ *
+ * - Without rounding options the difference goes through the Temporal compat layer's
+ *   `calendarDateUntil`, which is the polyfill's own `until` for `iso8601` and the TC39
+ *   `NonISODateUntil` answer for other calendars (CORE-6 D1, D6, D7 and the corrected calendars).
+ * - With `smallestUnit`, `roundingIncrement` or `roundingMode`, a calendar whose compat is needed
+ *   goes through `plainDateUntilWithRounding` (TC39 `DifferenceTemporalPlainDate` in the plain
+ *   context, `GetUTCEpochNanoseconds`); every other calendar is the polyfill's own `until`.
+ *
+ * @param start PlainDate the difference starts from
+ * @param end PlainDate in the same calendar
+ * @param largestUnit a date unit, singular or plural
+ * @param options optional DifferenceOptions rounding controls
+ * @returns the difference as a Temporal.Duration; throws RangeError on invalid input
+ *
+ * @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) {
+        return Temporal.Duration.from(calendarDateUntil(start, end, singularDateUnit(largestUnit)));
+    }
+    const untilOptions = {
+        largestUnit: largestUnit,
+        smallestUnit: options.smallestUnit,
+        roundingIncrement: options.roundingIncrement,
+        roundingMode: options.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
+    // component. Two PlainDates have none, so the target always lands on a date the window already
+    // reaches and the defect is unreachable through this function — measured over ~1.96M rows
+    // against the raw polyfill, in both directions, with zero divergence (CORE-8 review, #253).
+    if (start.calendarId === end.calendarId &&
+        isCalendarArithmeticCompatNeeded(start.calendarId)) {
+        return plainDateUntilWithRounding(start, end, untilOptions);
+    }
+    return start.until(end, untilOptions);
+}

package/dist/internal/plainFormatOptions.d.ts

@@ -0,0 +1,59 @@
+type Options = Intl.DateTimeFormatOptions;
+/**
+ * Map a `timeStyle` to the one a plain value may use.
+ *
+ * - CLDR's `long` and `full` time formats are the ones carrying a
+ *   `timeZoneName`. AdjustDateTimeStyleFormat removes that field and asks the
+ *   format matcher for a format with the remaining fields. Which pattern the
+ *   best-fit matcher picks is implementation-defined; GMT uses the locale's
+ *   own `medium` time format, which has exactly the same fields (hour, minute,
+ *   second, day period) and no zone. Checked against ICU 78 for 85
+ *   languages, alone and combined with `dateStyle: "full"`.
+ *
+ * @param timeStyle the caller's `timeStyle`
+ * @returns `"medium"` for `"long"`/`"full"`, otherwise the input
+ */
+export declare function plainTimeStyle<T extends Options["timeStyle"]>(timeStyle: T): T | "medium";
+/**
+ * Resolve caller options into runtime `Intl.DateTimeFormat` options that
+ * format a PlainDate: date fields only, never a time or zone field.
+ *
+ * - Returns `null` where Temporal throws a TypeError: `timeStyle` without
+ *   `dateStyle` ([[TemporalPlainDateFormat]] is null), or only non-date
+ *   fields (GetDateTimeFormat returns null).
+ * - Validation of the options themselves (invalid values, styles mixed with
+ *   fields) is left to the caller constructing a formatter with `options`.
+ *
+ * @param options caller's `Intl.DateTimeFormatOptions`
+ * @returns runtime options anchored at UTC, or `null` when no format exists
+ */
+export declare function plainDateFormatOptions(options: Options): Options | null;
+/**
+ * Resolve caller options into runtime `Intl.DateTimeFormat` options that
+ * format a PlainTime: time fields only, never a date, era or zone field.
+ *
+ * - Returns `null` where Temporal throws a TypeError: a `dateStyle`
+ *   (CreateDateTimeFormat with required ~time~), or only non-time fields
+ *   (GetDateTimeFormat returns null).
+ * - `era` and `timeZoneName` are not inherited (GetDateTimeFormat ~relevant~),
+ *   so with no time field hour, minute and second default to `"numeric"`.
+ * - A `long`/`full` `timeStyle` is mapped through {@link plainTimeStyle}.
+ *
+ * @param options caller's `Intl.DateTimeFormatOptions`
+ * @returns runtime options anchored at UTC, or `null` when no format exists
+ */
+export declare function plainTimeFormatOptions(options: Options): Options | null;
+/**
+ * Resolve caller options into runtime `Intl.DateTimeFormat` options that
+ * format a PlainDateTime: date and time fields, never a zone field.
+ *
+ * - `timeZoneName` is not inherited (GetDateTimeFormat ~relevant~), and a
+ *   `long`/`full` `timeStyle` is mapped through {@link plainTimeStyle}.
+ * - With no date or time field and no style, year, month, day, hour, minute
+ *   and second default to `"numeric"` (defaults ~all~).
+ *
+ * @param options caller's `Intl.DateTimeFormatOptions`
+ * @returns runtime options anchored at UTC
+ */
+export declare function plainDateTimeFormatOptions(options: Options): Options;
+export {};

package/dist/internal/plainFormatOptions.js

@@ -0,0 +1,165 @@
+// Option resolution for formatting a zoneless Temporal value (PlainDate,
+// PlainDateTime, PlainTime) through the runtime's `Intl.DateTimeFormat`, which only
+// formats instants. The rules are the Temporal proposal's ECMA-402
+// amendments (CreateDateTimeFormat, GetDateTimeFormat with inherit
+// ~relevant~, AdjustDateTimeStyleFormat); the formatter is then anchored at
+// UTC, which is an implementation detail and must never surface as a field.
+// GetDateTimeFormat requiredOptions for ~date~ and ~time~.
+const DATE_FIELDS = ["weekday", "year", "month", "day"];
+const TIME_FIELDS = [
+    "dayPeriod",
+    "hour",
+    "minute",
+    "second",
+    "fractionalSecondDigits",
+];
+// Options that configure the DateTimeFormat object itself rather than the
+// selected format record, so they carry over unchanged. `timeZone` is left
+// out: a plain value is always formatted at the UTC anchor.
+const FORMATTER_OPTIONS = [
+    "localeMatcher",
+    "calendar",
+    "numberingSystem",
+    "hour12",
+    "hourCycle",
+    "formatMatcher",
+];
+function formatterOptions(options) {
+    const out = { timeZone: "UTC" };
+    for (const key of FORMATTER_OPTIONS) {
+        if (options[key] !== undefined)
+            out[key] = options[key];
+    }
+    return out;
+}
+function pickFields(options, fields) {
+    const out = {};
+    for (const key of fields) {
+        if (options[key] !== undefined)
+            out[key] = options[key];
+    }
+    return out;
+}
+/**
+ * Map a `timeStyle` to the one a plain value may use.
+ *
+ * - CLDR's `long` and `full` time formats are the ones carrying a
+ *   `timeZoneName`. AdjustDateTimeStyleFormat removes that field and asks the
+ *   format matcher for a format with the remaining fields. Which pattern the
+ *   best-fit matcher picks is implementation-defined; GMT uses the locale's
+ *   own `medium` time format, which has exactly the same fields (hour, minute,
+ *   second, day period) and no zone. Checked against ICU 78 for 85
+ *   languages, alone and combined with `dateStyle: "full"`.
+ *
+ * @param timeStyle the caller's `timeStyle`
+ * @returns `"medium"` for `"long"`/`"full"`, otherwise the input
+ */
+export function plainTimeStyle(timeStyle) {
+    return timeStyle === "long" || timeStyle === "full" ? "medium" : timeStyle;
+}
+/**
+ * Resolve caller options into runtime `Intl.DateTimeFormat` options that
+ * format a PlainDate: date fields only, never a time or zone field.
+ *
+ * - Returns `null` where Temporal throws a TypeError: `timeStyle` without
+ *   `dateStyle` ([[TemporalPlainDateFormat]] is null), or only non-date
+ *   fields (GetDateTimeFormat returns null).
+ * - Validation of the options themselves (invalid values, styles mixed with
+ *   fields) is left to the caller constructing a formatter with `options`.
+ *
+ * @param options caller's `Intl.DateTimeFormatOptions`
+ * @returns runtime options anchored at UTC, or `null` when no format exists
+ */
+export function plainDateFormatOptions(options) {
+    const base = formatterOptions(options);
+    if (options.dateStyle !== undefined || options.timeStyle !== undefined) {
+        if (options.dateStyle === undefined)
+            return null;
+        return { ...base, dateStyle: options.dateStyle };
+    }
+    const dateFields = pickFields(options, DATE_FIELDS);
+    const anyPresent = [...DATE_FIELDS, ...TIME_FIELDS].some((key) => options[key] !== undefined);
+    const era = options.era === undefined ? {} : { era: options.era };
+    if (Object.keys(dateFields).length > 0) {
+        return { ...base, ...era, ...dateFields };
+    }
+    if (anyPresent)
+        return null;
+    return {
+        ...base,
+        ...era,
+        year: "numeric",
+        month: "numeric",
+        day: "numeric",
+    };
+}
+/**
+ * Resolve caller options into runtime `Intl.DateTimeFormat` options that
+ * format a PlainTime: time fields only, never a date, era or zone field.
+ *
+ * - Returns `null` where Temporal throws a TypeError: a `dateStyle`
+ *   (CreateDateTimeFormat with required ~time~), or only non-time fields
+ *   (GetDateTimeFormat returns null).
+ * - `era` and `timeZoneName` are not inherited (GetDateTimeFormat ~relevant~),
+ *   so with no time field hour, minute and second default to `"numeric"`.
+ * - A `long`/`full` `timeStyle` is mapped through {@link plainTimeStyle}.
+ *
+ * @param options caller's `Intl.DateTimeFormatOptions`
+ * @returns runtime options anchored at UTC, or `null` when no format exists
+ */
+export function plainTimeFormatOptions(options) {
+    const base = formatterOptions(options);
+    if (options.dateStyle !== undefined)
+        return null;
+    if (options.timeStyle !== undefined) {
+        return { ...base, timeStyle: plainTimeStyle(options.timeStyle) };
+    }
+    const timeFields = pickFields(options, TIME_FIELDS);
+    if (Object.keys(timeFields).length > 0) {
+        return { ...base, ...timeFields };
+    }
+    if (DATE_FIELDS.some((key) => options[key] !== undefined))
+        return null;
+    return { ...base, hour: "numeric", minute: "numeric", second: "numeric" };
+}
+/**
+ * Resolve caller options into runtime `Intl.DateTimeFormat` options that
+ * format a PlainDateTime: date and time fields, never a zone field.
+ *
+ * - `timeZoneName` is not inherited (GetDateTimeFormat ~relevant~), and a
+ *   `long`/`full` `timeStyle` is mapped through {@link plainTimeStyle}.
+ * - With no date or time field and no style, year, month, day, hour, minute
+ *   and second default to `"numeric"` (defaults ~all~).
+ *
+ * @param options caller's `Intl.DateTimeFormatOptions`
+ * @returns runtime options anchored at UTC
+ */
+export function plainDateTimeFormatOptions(options) {
+    const base = formatterOptions(options);
+    if (options.dateStyle !== undefined || options.timeStyle !== undefined) {
+        return {
+            ...base,
+            ...(options.dateStyle === undefined
+                ? {}
+                : { dateStyle: options.dateStyle }),
+            ...(options.timeStyle === undefined
+                ? {}
+                : { timeStyle: plainTimeStyle(options.timeStyle) }),
+        };
+    }
+    const fields = pickFields(options, [...DATE_FIELDS, ...TIME_FIELDS]);
+    const era = options.era === undefined ? {} : { era: options.era };
+    if (Object.keys(fields).length > 0) {
+        return { ...base, ...era, ...fields };
+    }
+    return {
+        ...base,
+        ...era,
+        year: "numeric",
+        month: "numeric",
+        day: "numeric",
+        hour: "numeric",
+        minute: "numeric",
+        second: "numeric",
+    };
+}

package/dist/internal/resolveDateTimeUnit.d.ts

@@ -3,9 +3,12 @@
  *
  * - Accepts singular ("day"), plural ("days"), and already-singular forms.
  * - Returns the original string if it is not a recognized DateTimeUnit.
+ * - Returns a non-string input unchanged, so callers can pass raw option values and let their own
+ *   validator reject them (Temporal §13.17 GetTemporalUnitValuedOption accepts both spellings).
  * - Singular counterpart of `resolveDurationUnit`, which normalizes to plurals.
  *
- * @param unit raw unit string from caller input
+ * @param unit raw unit value from caller input
  * @returns normalized singular unit string, or the original if not recognized
  */
 export declare function resolveDateTimeUnit(unit: string): string;
+export declare function resolveDateTimeUnit(unit: unknown): unknown;

package/dist/internal/resolveDateTimeUnit.js

@@ -1,16 +1,6 @@
-import { isValidDateTimeUnit } from "../plain/validate/index.js";
-/**
- * Normalize a date-time unit string to its singular form.
- *
- * - Accepts singular ("day"), plural ("days"), and already-singular forms.
- * - Returns the original string if it is not a recognized DateTimeUnit.
- * - Singular counterpart of `resolveDurationUnit`, which normalizes to plurals.
- *
- * @param unit raw unit string from caller input
- * @returns normalized singular unit string, or the original if not recognized
- */
+import { isValidDateTimeUnit } from "../plain/validate/isValidDateTimeUnit.js";
 export function resolveDateTimeUnit(unit) {
-    if (isValidDateTimeUnit(unit)) {
+    if (typeof unit !== "string" || isValidDateTimeUnit(unit)) {
         return unit;
     }
     if (unit.endsWith("s")) {

package/dist/internal/resolveDurationRelativeTo.d.ts

@@ -1,29 +1,35 @@
 import type { DurationRelativeTo } from "../types/index.js";
 /**
- * Resolve a `DurationRelativeTo` value for `Temporal.Duration`'s `relativeTo` option, converting
- * a GMT calendar-annotated PlainDate string (`"5784-06-15[u-ca=hebrew]"`, as produced by
- * `convertDateToCalendar`) into the `Temporal.PlainDate` it actually names before handing it to
- * Temporal.
+ * Resolve a `DurationRelativeTo` value for `Temporal.Duration`'s `relativeTo` option.
  *
- * Without this, Temporal's own `relativeTo` string parsing reads GMT's native-digit shape as if
- * it were Temporal's ISO-digit `[u-ca=...]` convention instead (see
- * `context/coding-standards.md`'s E1 scoped-exception note on the two conventions), silently
- * resolving to the wrong date with no error — e.g. `relativeTo: "5784-06-15[u-ca=hebrew]"`
- * previously returned the day count for Gregorian year 5784, not the Hebrew date it names. Found
- * and fixed as part of E5 (issue #78); this is D1's "`duration/`'s `relativeTo` accepts the GMT
- * shape only" decision of record.
+ * - Every string is ISO 8601 extended format before its first `[`: with a
+ *   time zone annotation, the strict zoned shape (`zonedDateTimeBody`: `<date>T<time>`, then
+ *   nothing, `Z` or `±HH:MM[:SS[.fraction]]`); otherwise GMT's strict date (`plainDate`) or
+ *   date-time (`plainDateTime`). Basic format (`"20241003"`), a space or lower-case `t` separator,
+ *   a lower-case `z`, an hour-only time or offset, a UTC offset without a time zone annotation
+ *   and a zoned date without a time throw, although Temporal's `ParseTemporalRelativeToString`
+ *   reads them.
+ * - A string with a `u-ca` annotation is read as Temporal's `ParseTemporalRelativeToString` reads
+ *   it: with a time zone annotation it is a ZonedDateTime (`"2024-02-24T00:00:00-05:00[America/New_York][u-ca=hebrew]"`,
+ *   `parseCalendarZonedValue`), otherwise a PlainDate (`"2024-02-24[u-ca=hebrew]"`, or a date-time
+ *   whose time Temporal drops, `parseCalendarDateValue`). Annotations follow Temporal's
+ *   grammar: elective unknown ones are ignored, the first `u-ca` wins, and an unknown critical
+ *   annotation, a critical duplicate calendar, a calendar before the zone and `;era=` throw. The
+ *   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 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`.
+ * - Every other `relativeTo` (a strict extended string without a calendar annotation, or a `PlainDate`/`PlainDateTime`/
+ *   `ZonedDateTime` object or `-Like`) passes through unchanged.
  *
- * Every other `relativeTo` shape (a plain ISO string, a `PlainDateTime`/`ZonedDateTime` object
- * or `-Like`, or any string that isn't a GMT calendar-annotated PlainDate) passes through
- * unchanged — GMT's calendar-string contract only covers `plain/` `PlainDate` (D1).
+ * A PlainDate string resolves to a `Temporal.PlainDateTime` (midnight, same calendar) only because
+ * the polyfill's TypeScript declaration and GMT's `DurationRelativeTo` type list `PlainDateTime`,
+ * not `PlainDate`. Temporal's `GetTemporalRelativeToOption` converts a `PlainDateTime` with
+ * `CreateTemporalDate` and drops the time, so the result is identical.
  *
- * Resolves to a `Temporal.PlainDateTime` (midnight, same calendar) rather than a bare
- * `Temporal.PlainDate` — verified equivalent at runtime (`.total`/`.round`/`.compare` all
- * produce the identical result either way) and `PlainDateTime` is the type Temporal's own
- * `relativeTo` option signature actually accepts, unlike `PlainDate`.
- *
- * Throws if the calendar-annotated string is malformed. Callers already wrap the Temporal call
- * consuming this in `try { ... } catch { return sentinel }` per GMT's contract, so this composes
- * directly into that same block rather than needing its own try/catch.
+ * Throws on invalid input. Callers already wrap the Temporal call consuming this in
+ * `try { ... } catch { return sentinel }` per GMT's contract.
  */
 export declare function resolveDurationRelativeTo(relativeTo: DurationRelativeTo | undefined): DurationRelativeTo | undefined;

package/dist/internal/resolveDurationRelativeTo.js

@@ -1,35 +1,79 @@
-import { calendarDate } from "../regex/index.js";
-import { parseCalendarDateValue } from "./calendarDateString.js";
+import { plainDate } from "../regex/date.js";
+import { plainDateTime } from "../regex/date-time.js";
+import { parseCalendarDateValue, temporalStringLeapSecond, } from "./calendarDateString.js";
+import { parseCalendarZonedValue } from "./calendarZonedString.js";
+import { hasZonedDateTimeShape, isoStringBody } from "./isoStringBody.js";
 /**
- * Resolve a `DurationRelativeTo` value for `Temporal.Duration`'s `relativeTo` option, converting
- * a GMT calendar-annotated PlainDate string (`"5784-06-15[u-ca=hebrew]"`, as produced by
- * `convertDateToCalendar`) into the `Temporal.PlainDate` it actually names before handing it to
- * Temporal.
- *
- * Without this, Temporal's own `relativeTo` string parsing reads GMT's native-digit shape as if
- * it were Temporal's ISO-digit `[u-ca=...]` convention instead (see
- * `context/coding-standards.md`'s E1 scoped-exception note on the two conventions), silently
- * resolving to the wrong date with no error — e.g. `relativeTo: "5784-06-15[u-ca=hebrew]"`
- * previously returned the day count for Gregorian year 5784, not the Hebrew date it names. Found
- * and fixed as part of E5 (issue #78); this is D1's "`duration/`'s `relativeTo` accepts the GMT
- * shape only" decision of record.
+ * 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.
+ */
+const anyCalendarAnnotation = /\[!?u-ca=/i;
+/**
+ * A time zone annotation: the first bracketed annotation has no `=` (RFC 9557 §4.1; Temporal's
+ * `TimeZoneAnnotation` precedes every other annotation). This only picks the branch; Temporal
+ * parses the string.
+ */
+const timeZoneAnnotation = /^[^[]*\[!?[^=\]]*\]/;
+/**
+ * GMT's strict written shape for a `relativeTo` string: a string with a time zone annotation is
+ * zoned (Temporal's `ParseTemporalRelativeToString` branch) and must be `zonedDateTimeBody`; any
+ * other is a date or date-time.
+ */
+function hasRelativeToShape(value) {
+    if (timeZoneAnnotation.test(value)) {
+        return hasZonedDateTimeShape(value);
+    }
+    const body = isoStringBody(value);
+    return plainDate.test(body) || plainDateTime.test(body);
+}
+/**
+ * Resolve a `DurationRelativeTo` value for `Temporal.Duration`'s `relativeTo` option.
  *
- * Every other `relativeTo` shape (a plain ISO string, a `PlainDateTime`/`ZonedDateTime` object
- * or `-Like`, or any string that isn't a GMT calendar-annotated PlainDate) passes through
- * unchanged — GMT's calendar-string contract only covers `plain/` `PlainDate` (D1).
+ * - Every string is ISO 8601 extended format before its first `[`: with a
+ *   time zone annotation, the strict zoned shape (`zonedDateTimeBody`: `<date>T<time>`, then
+ *   nothing, `Z` or `±HH:MM[:SS[.fraction]]`); otherwise GMT's strict date (`plainDate`) or
+ *   date-time (`plainDateTime`). Basic format (`"20241003"`), a space or lower-case `t` separator,
+ *   a lower-case `z`, an hour-only time or offset, a UTC offset without a time zone annotation
+ *   and a zoned date without a time throw, although Temporal's `ParseTemporalRelativeToString`
+ *   reads them.
+ * - A string with a `u-ca` annotation is read as Temporal's `ParseTemporalRelativeToString` reads
+ *   it: with a time zone annotation it is a ZonedDateTime (`"2024-02-24T00:00:00-05:00[America/New_York][u-ca=hebrew]"`,
+ *   `parseCalendarZonedValue`), otherwise a PlainDate (`"2024-02-24[u-ca=hebrew]"`, or a date-time
+ *   whose time Temporal drops, `parseCalendarDateValue`). Annotations follow Temporal's
+ *   grammar: elective unknown ones are ignored, the first `u-ca` wins, and an unknown critical
+ *   annotation, a critical duplicate calendar, a calendar before the zone and `;era=` throw. The
+ *   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 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`.
+ * - Every other `relativeTo` (a strict extended string without a calendar annotation, or a `PlainDate`/`PlainDateTime`/
+ *   `ZonedDateTime` object or `-Like`) passes through unchanged.
  *
- * Resolves to a `Temporal.PlainDateTime` (midnight, same calendar) rather than a bare
- * `Temporal.PlainDate` — verified equivalent at runtime (`.total`/`.round`/`.compare` all
- * produce the identical result either way) and `PlainDateTime` is the type Temporal's own
- * `relativeTo` option signature actually accepts, unlike `PlainDate`.
+ * A PlainDate string resolves to a `Temporal.PlainDateTime` (midnight, same calendar) only because
+ * the polyfill's TypeScript declaration and GMT's `DurationRelativeTo` type list `PlainDateTime`,
+ * not `PlainDate`. Temporal's `GetTemporalRelativeToOption` converts a `PlainDateTime` with
+ * `CreateTemporalDate` and drops the time, so the result is identical.
  *
- * Throws if the calendar-annotated string is malformed. Callers already wrap the Temporal call
- * consuming this in `try { ... } catch { return sentinel }` per GMT's contract, so this composes
- * directly into that same block rather than needing its own try/catch.
+ * Throws on invalid input. Callers already wrap the Temporal call consuming this in
+ * `try { ... } catch { return sentinel }` per GMT's contract.
  */
 export function resolveDurationRelativeTo(relativeTo) {
-    if (typeof relativeTo !== "string" || !calendarDate.test(relativeTo)) {
+    if (typeof relativeTo !== "string") {
         return relativeTo;
     }
+    if (temporalStringLeapSecond.test(relativeTo)) {
+        throw new RangeError(`Leap seconds are not supported: ${relativeTo}`);
+    }
+    if (!hasRelativeToShape(relativeTo)) {
+        throw new RangeError(`Not an extended ISO 8601 date, date-time or zoned date-time: ${relativeTo}`);
+    }
+    if (!anyCalendarAnnotation.test(relativeTo)) {
+        return relativeTo;
+    }
+    if (timeZoneAnnotation.test(relativeTo)) {
+        return parseCalendarZonedValue(relativeTo);
+    }
     return parseCalendarDateValue(relativeTo).toPlainDateTime();
 }

package/dist/internal/resolveDurationUnit.d.ts

@@ -3,8 +3,11 @@
  *
  * - Accepts singular ("day"), plural ("days"), and already-plural forms.
  * - Returns the original string if it is not a recognized DateTimeDurationUnit.
+ * - Returns a non-string input unchanged, so callers can pass raw option values and let their own
+ *   validator reject them.
  *
- * @param unit raw unit string from caller input
+ * @param unit raw unit value from caller input
  * @returns normalized plural unit string, or the original if not recognized
  */
 export declare function resolveDurationUnit(unit: string): string;
+export declare function resolveDurationUnit(unit: unknown): unknown;

package/dist/internal/resolveDurationUnit.js

@@ -1,15 +1,6 @@
-import { isValidDateTimeDurationUnit } from "../plain/validate/index.js";
-/**
- * Normalize a duration unit string to its plural form.
- *
- * - Accepts singular ("day"), plural ("days"), and already-plural forms.
- * - Returns the original string if it is not a recognized DateTimeDurationUnit.
- *
- * @param unit raw unit string from caller input
- * @returns normalized plural unit string, or the original if not recognized
- */
+import { isValidDateTimeDurationUnit } from "../plain/validate/isValidDateTimeDurationUnit.js";
 export function resolveDurationUnit(unit) {
-    if (isValidDateTimeDurationUnit(unit)) {
+    if (typeof unit !== "string" || isValidDateTimeDurationUnit(unit)) {
         return unit;
     }
     if (unit.endsWith("s")) {

package/dist/internal/resolveLocale.d.ts

@@ -0,0 +1,37 @@
+/**
+ * A locale argument: one BCP 47 tag, or a preference list of tags (ECMA-402 `locales`).
+ */
+export type LocalesArgument = string | string[];
+/**
+ * Resolve a `locale` argument to the single BCP 47 tag a locale-aware function reads.
+ *
+ * - Follows ECMA-402 CanonicalizeLocaleList: a string is a one-tag list, every tag is
+ *   canonicalized (`"EN-us"` → `"en-US"`) and duplicates are dropped.
+ * - The first tag with available locale data wins (`Intl.DateTimeFormat.supportedLocalesOf`), as
+ *   ECMA-402's locale negotiation picks; a list with no available tag keeps its first tag, exactly
+ *   as that tag passed alone would be read.
+ * - `undefined` and an empty list resolve to the default locale.
+ * - A malformed tag anywhere in the list, a non-string element, or any other type is invalid and
+ *   resolves to `null`, which callers map to their sentinel (ECMA-402 throws a RangeError/TypeError).
+ *
+ * @param locales raw locale argument from caller input
+ * @returns the resolved BCP 47 tag, or `null` when the argument is invalid
+ */
+export declare function resolveLocale(locales: unknown): string | null;
+/**
+ * Resolve the `locale` argument of a function whose locale is required, to the single BCP 47 tag
+ * it reads, or `null` (the caller's sentinel).
+ *
+ * - An omitted locale (`undefined`) and an empty list both name no locale, so both are `null`.
+ *   ECMA-402 would resolve an empty list to the host default locale; a required locale exists to
+ *   keep the result independent of the host, so GMT treats `[]` as omitted (house rule).
+ * - Anything else resolves as `resolveLocale` does.
+ *
+ * @param locales raw locale argument from caller input
+ * @returns the resolved BCP 47 tag, or `null` when the argument is omitted, empty or invalid
+ *
+ * @example resolveRequiredLocale("EN-us") // "en-US"
+ * @example resolveRequiredLocale(undefined) // null
+ * @example resolveRequiredLocale([]) // null
+ */
+export declare function resolveRequiredLocale(locales: unknown): string | null;

package/dist/internal/resolveLocale.js

@@ -0,0 +1,59 @@
+/**
+ * Resolve a `locale` argument to the single BCP 47 tag a locale-aware function reads.
+ *
+ * - Follows ECMA-402 CanonicalizeLocaleList: a string is a one-tag list, every tag is
+ *   canonicalized (`"EN-us"` → `"en-US"`) and duplicates are dropped.
+ * - The first tag with available locale data wins (`Intl.DateTimeFormat.supportedLocalesOf`), as
+ *   ECMA-402's locale negotiation picks; a list with no available tag keeps its first tag, exactly
+ *   as that tag passed alone would be read.
+ * - `undefined` and an empty list resolve to the default locale.
+ * - A malformed tag anywhere in the list, a non-string element, or any other type is invalid and
+ *   resolves to `null`, which callers map to their sentinel (ECMA-402 throws a RangeError/TypeError).
+ *
+ * @param locales raw locale argument from caller input
+ * @returns the resolved BCP 47 tag, or `null` when the argument is invalid
+ */
+export function resolveLocale(locales) {
+    if (locales !== undefined &&
+        typeof locales !== "string" &&
+        !Array.isArray(locales)) {
+        return null;
+    }
+    try {
+        const canonical = Intl.getCanonicalLocales(locales);
+        if (canonical.length === 0) {
+            return new Intl.DateTimeFormat().resolvedOptions().locale;
+        }
+        if (canonical.length === 1)
+            return canonical[0] ?? null;
+        return (Intl.DateTimeFormat.supportedLocalesOf(canonical)[0] ??
+            canonical[0] ??
+            null);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Resolve the `locale` argument of a function whose locale is required, to the single BCP 47 tag
+ * it reads, or `null` (the caller's sentinel).
+ *
+ * - An omitted locale (`undefined`) and an empty list both name no locale, so both are `null`.
+ *   ECMA-402 would resolve an empty list to the host default locale; a required locale exists to
+ *   keep the result independent of the host, so GMT treats `[]` as omitted (house rule).
+ * - Anything else resolves as `resolveLocale` does.
+ *
+ * @param locales raw locale argument from caller input
+ * @returns the resolved BCP 47 tag, or `null` when the argument is omitted, empty or invalid
+ *
+ * @example resolveRequiredLocale("EN-us") // "en-US"
+ * @example resolveRequiredLocale(undefined) // null
+ * @example resolveRequiredLocale([]) // null
+ */
+export function resolveRequiredLocale(locales) {
+    if (locales === undefined)
+        return null;
+    if (Array.isArray(locales) && locales.length === 0)
+        return null;
+    return resolveLocale(locales);
+}