@northguild/gmt 1.14.2 → 1.16.0

package/dist/internal/patternToken.js

@@ -1,3 +1,4 @@
+import { resolveLocale } from "./resolveLocale.js";
 import { getLocaleEraNames } from "../plain/locale/getLocaleEraNames.js";
 import { getLocaleMeridiems } from "../plain/locale/getLocaleMeridiems.js";
 import { getLocaleMonthNames } from "../plain/locale/getLocaleMonthNames.js";
@@ -367,14 +368,19 @@ export function parseValueWithPattern(value, pattern, locale, allowedFields) {
         return null;
     if (typeof pattern !== "string" || pattern.length === 0)
         return null;
-    if (locale !== undefined && typeof locale !== "string")
-        return null;
     // No `locale` is required to parse a pattern containing only numeric
     // tokens, but a name-based token (MMM/MMMM/EEE/EEEE/a/GG/GGGG) needs
     // *some* locale to resolve against — default to "en-US" rather than
     // silently returning "" for every caller who didn't have another
-    // locale in mind.
-    const resolvedLocale = typeof locale === "string" ? locale : "en-US";
+    // locale in mind. An empty preference list names no locale either, so
+    // it takes that same default: ECMA-402 ResolveLocale would answer `[]`
+    // with the *host* locale, which would make a decoder of a fixed
+    // producer format read differently on a French machine (house rule,
+    // ./resolveLocale.ts).
+    const omitted = locale === undefined || (Array.isArray(locale) && locale.length === 0);
+    const resolvedLocale = omitted ? "en-US" : resolveLocale(locale);
+    if (resolvedLocale === null)
+        return null;
     const compiled = compilePattern(pattern, allowedFields, resolvedLocale);
     if (compiled === null)
         return null;

package/dist/internal/plainDateAdd.d.ts

@@ -0,0 +1,20 @@
+import { Temporal } from "@js-temporal/polyfill";
+/**
+ * `date.add(duration, { overflow })` for a PlainDate in any calendar.
+ *
+ * - `iso8601` is the polyfill's own `add`, untouched.
+ * - Other calendars go through the Temporal compat layer's `calendarDateAdd` (CORE-6: the polyfill's
+ *   calendar add throws near the range limits and is wrong in the corrected calendar ranges). Time
+ *   fields become whole days exactly as TC39 `ToDateDurationRecordWithoutTime` does: the time
+ *   duration in nanoseconds, truncated toward zero to 24-hour days, added to `days`.
+ * - The duration is validated by `Temporal.Duration.from`, as `add` itself does.
+ *
+ * @param date PlainDate to add to
+ * @param duration a DurationLike (negate it to subtract)
+ * @param overflow "constrain" (default, as in Temporal) | "reject"
+ * @returns the resulting PlainDate in `date`'s calendar; throws on invalid input or out of range
+ *
+ * @example plainDateAdd(Temporal.PlainDate.from("2024-01-31"), { months: 1 }, "constrain").toString() // "2024-02-29"
+ * @example plainDateAdd(Temporal.PlainDate.from("2024-01-31"), { months: 1 }, "reject") // throws RangeError
+ */
+export declare function plainDateAdd(date: Temporal.PlainDate, duration: Temporal.Duration | Temporal.DurationLike, overflow?: "constrain" | "reject"): Temporal.PlainDate;

package/dist/internal/plainDateAdd.js

@@ -0,0 +1,42 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { calendarDateAdd } from "./temporalCompat/index.js";
+const NANOSECONDS_PER_HOUR = 3600000000000n;
+const NANOSECONDS_PER_MINUTE = 60000000000n;
+const NANOSECONDS_PER_SECOND = 1000000000n;
+const NANOSECONDS_PER_DAY = 86400000000000n;
+/**
+ * `date.add(duration, { overflow })` for a PlainDate in any calendar.
+ *
+ * - `iso8601` is the polyfill's own `add`, untouched.
+ * - Other calendars go through the Temporal compat layer's `calendarDateAdd` (CORE-6: the polyfill's
+ *   calendar add throws near the range limits and is wrong in the corrected calendar ranges). Time
+ *   fields become whole days exactly as TC39 `ToDateDurationRecordWithoutTime` does: the time
+ *   duration in nanoseconds, truncated toward zero to 24-hour days, added to `days`.
+ * - The duration is validated by `Temporal.Duration.from`, as `add` itself does.
+ *
+ * @param date PlainDate to add to
+ * @param duration a DurationLike (negate it to subtract)
+ * @param overflow "constrain" (default, as in Temporal) | "reject"
+ * @returns the resulting PlainDate in `date`'s calendar; throws on invalid input or out of range
+ *
+ * @example plainDateAdd(Temporal.PlainDate.from("2024-01-31"), { months: 1 }, "constrain").toString() // "2024-02-29"
+ * @example plainDateAdd(Temporal.PlainDate.from("2024-01-31"), { months: 1 }, "reject") // throws RangeError
+ */
+export function plainDateAdd(date, duration, overflow = "constrain") {
+    if (date.calendarId === "iso8601") {
+        return date.add(duration, { overflow });
+    }
+    const { years, months, weeks, days, hours, minutes, seconds, milliseconds, microseconds, nanoseconds, } = Temporal.Duration.from(duration);
+    const timeNanoseconds = BigInt(hours) * NANOSECONDS_PER_HOUR +
+        BigInt(minutes) * NANOSECONDS_PER_MINUTE +
+        BigInt(seconds) * NANOSECONDS_PER_SECOND +
+        BigInt(milliseconds) * 1000000n +
+        BigInt(microseconds) * 1000n +
+        BigInt(nanoseconds);
+    return calendarDateAdd(date, {
+        years,
+        months,
+        weeks,
+        days: days + Number(timeNanoseconds / NANOSECONDS_PER_DAY),
+    }, overflow);
+}

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")) {