@northguild/gmt 1.14.2 → 1.16.0

package/dist/internal/httpDateFields.d.ts

@@ -0,0 +1,24 @@
+/** Date-time fields read from an RFC 9110 HTTP-date, before calendar validation. */
+export interface HttpDateFields {
+    /** ISO day of week 1 (Monday) – 7 (Sunday). */
+    dayOfWeek: number;
+    year: number;
+    month: number;
+    day: number;
+    hour: number;
+    minute: number;
+    second: number;
+}
+/**
+ * Read the fields of an RFC 9110 obsolete HTTP-date: `rfc850-date` or
+ * `asctime-date`. IMF-fixdate is read with the exported `httpDate` pattern.
+ *
+ * - Shape checks only: the calendar date and the day of week are left to the
+ *   caller (`Temporal.PlainDateTime.from` with `overflow: "reject"`).
+ * - An `rfc850-date` reads the clock (`Temporal.Now.instant`) to place its
+ *   two-digit year; that call throws if the clock cannot be read.
+ *
+ * @param value candidate obsolete HTTP-date
+ * @returns the fields, or `null` when `value` is neither obsolete format
+ */
+export declare function readObsoleteHttpDate(value: string): HttpDateFields | null;

package/dist/internal/httpDateFields.js

@@ -0,0 +1,86 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { ENGLISH_MONTH_NAMES, ENGLISH_WEEKDAY_NAMES, } from "./englishCalendarNames.js";
+// RFC 9110 §5.6.7 obsolete formats. HTTP-date is case-sensitive (%s strings).
+//   rfc850-date  = day-name-l "," SP date2 SP time-of-day SP GMT
+//   date2        = day "-" month "-" 2DIGIT
+// Capture groups: 1 day-name-l, 2 day, 3 month, 4 year, 5 hour, 6 minute, 7 second.
+const RFC850_DATE = /^(Monday|Tuesday|Wednesday|Thursday|Friday|Saturday|Sunday), (\d{2})-(Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec)-(\d{2}) (\d{2}):(\d{2}):(\d{2}) GMT$/;
+//   asctime-date = day-name SP date3 SP time-of-day SP year
+//   date3        = month SP ( 2DIGIT / ( SP 1DIGIT ))
+// Capture groups: 1 day-name, 2 month, 3 day, 4 hour, 5 minute, 6 second, 7 year.
+const ASCTIME_DATE = /^(Mon|Tue|Wed|Thu|Fri|Sat|Sun) (Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec) (\d{2}| \d) (\d{2}):(\d{2}):(\d{2}) (\d{4})$/;
+const LONG_WEEKDAY_NAMES = [
+    "Monday",
+    "Tuesday",
+    "Wednesday",
+    "Thursday",
+    "Friday",
+    "Saturday",
+    "Sunday",
+];
+function monthNumber(name) {
+    return (ENGLISH_MONTH_NAMES.indexOf(name) +
+        1);
+}
+// "Recipients of a timestamp value in rfc850-date format, which uses a
+// two-digit year, MUST interpret a timestamp that appears to be more than 50
+// years in the future as representing the most recent year in the past that
+// had the same last two digits." The year chosen is the latest one ending in
+// those digits whose timestamp is not more than 50 years after now.
+function resolveTwoDigitYear(twoDigits, fields) {
+    const limit = Temporal.Now.instant()
+        .toZonedDateTimeISO("UTC")
+        .add({ years: 50 })
+        .toPlainDateTime();
+    const isBeyondLimit = (year) => Temporal.PlainDateTime.compare({ ...fields, year }, limit) > 0;
+    let year = Math.floor(limit.year / 100) * 100 + twoDigits;
+    while (isBeyondLimit(year))
+        year -= 100;
+    while (!isBeyondLimit(year + 100))
+        year += 100;
+    return year;
+}
+/**
+ * Read the fields of an RFC 9110 obsolete HTTP-date: `rfc850-date` or
+ * `asctime-date`. IMF-fixdate is read with the exported `httpDate` pattern.
+ *
+ * - Shape checks only: the calendar date and the day of week are left to the
+ *   caller (`Temporal.PlainDateTime.from` with `overflow: "reject"`).
+ * - An `rfc850-date` reads the clock (`Temporal.Now.instant`) to place its
+ *   two-digit year; that call throws if the clock cannot be read.
+ *
+ * @param value candidate obsolete HTTP-date
+ * @returns the fields, or `null` when `value` is neither obsolete format
+ */
+export function readObsoleteHttpDate(value) {
+    const rfc850 = RFC850_DATE.exec(value);
+    if (rfc850 !== null) {
+        const [, dayName, day, month, year, hour, minute, second] = rfc850;
+        const fields = {
+            month: monthNumber(month),
+            day: Number(day),
+            hour: Number(hour),
+            minute: Number(minute),
+            second: Number(second),
+        };
+        return {
+            ...fields,
+            dayOfWeek: LONG_WEEKDAY_NAMES.indexOf(dayName) + 1,
+            year: resolveTwoDigitYear(Number(year), fields),
+        };
+    }
+    const asctime = ASCTIME_DATE.exec(value);
+    if (asctime !== null) {
+        const [, dayName, month, day, hour, minute, second, year] = asctime;
+        return {
+            dayOfWeek: ENGLISH_WEEKDAY_NAMES.indexOf(dayName) + 1,
+            year: Number(year),
+            month: monthNumber(month),
+            day: Number(day),
+            hour: Number(hour),
+            minute: Number(minute),
+            second: Number(second),
+        };
+    }
+    return null;
+}

package/dist/internal/index.d.ts

@@ -1,34 +1,53 @@
-export { advanceBusinessDays } from "./advanceBusinessDays.js";
-export { adjustZonedBusinessDays } from "./adjustZonedBusinessDays.js";
 export { advanceToWeekday } from "./advanceToWeekday.js";
-export { calendarDateParts, type CalendarDateStringParts, formatCalendarDate, parseCalendarDateValue, } from "./calendarDateString.js";
-export { isCalendarSystem, temporalCalendarIds } from "./calendarSystemIds.js";
+export { parseCalendarDateValue } from "./calendarDateString.js";
+export { canonicalCalendarSystem, isCalendarSystem } from "./calendarSystemIds.js";
 export { parseCalendarDatePairForArithmetic } from "./calendarDatePairPolicy.js";
 export { parseCalendarZonedPairForArithmetic } from "./calendarZonedPairPolicy.js";
 export { calendarOfAllDateValues, calendarSystemOfDateValue, } from "./calendarValueOfDate.js";
 export { calendarOfAllZonedValues, calendarSystemOfZonedValue, } from "./calendarValueOfZoned.js";
 export { formatZonedInCalendar, parseCalendarZonedValue, } from "./calendarZonedString.js";
 export { cycleFieldValue } from "./cycleFieldValue.js";
+export { fiscalPeriodOfWeek, fiscalYearOf } from "./fiscalCalendar.js";
+export { floorDivide } from "./floorDivide.js";
+export { DOT_NET_TICKS_EPOCH_OFFSET, EXCEL_1900_EPOCH_NANOSECONDS, EXCEL_1900_PHANTOM_END_NANOSECONDS, EXCEL_1900_PRE_PHANTOM_EPOCH_NANOSECONDS, EXCEL_1904_EPOCH_NANOSECONDS, EXCEL_PHANTOM_SERIAL, FILE_TIME_EPOCH_OFFSET_TICKS, MAX_DOT_NET_TICKS, MAX_EXCEL_1900_SERIAL_EXCLUSIVE, MAX_EXCEL_1904_SERIAL_EXCLUSIVE, MAX_FILE_TIME, MILLISECONDS_PER_DAY, MIN_DOT_NET_TICKS, MIN_EXCEL_1900_SERIAL, MIN_EXCEL_1904_SERIAL, MIN_FILE_TIME, MIN_PG_MICROSECONDS, NANOSECONDS_PER_DAY, NANOSECONDS_PER_DAY_NUMBER, NANOSECONDS_PER_MICROSECOND, NANOSECONDS_PER_MILLISECOND, NANOSECONDS_PER_SECOND, NANOSECONDS_PER_TICK, NTP_EPOCH_OFFSET_NANOSECONDS, NTP_ERA_UNITS, NTP_UNITS_PER_SECOND, PG_EPOCH_OFFSET_MICROSECONDS, } from "./foreignEpochs.js";
+export { isValidEpochNanoseconds, MAX_EPOCH_NANOSECOND_DIGITS, } from "./epochNanoseconds.js";
 export { dateCycleFieldBounds } from "./dateCycleFieldBounds.js";
 export { timeCycleFieldBounds } from "./timeCycleFieldBounds.js";
 export { durationUntilString } from "./durationUntilString.js";
-export { calendarDateStringParts, formatDateInCalendar, } from "./formatDateInCalendar.js";
-export { hasCalendarAnnotation } from "./hasCalendarAnnotation.js";
+export { formatDateInCalendar } from "./formatDateInCalendar.js";
+export { halfOpenAbuts, halfOpenContainsPoint, halfOpenContainsSpan, halfOpenDifference, halfOpenIntersection, halfOpenMerge, halfOpenOverlap, halfOpenUnion, halfOpenXor, } from "./halfOpenIntervals.js";
+export { isoStringBody } from "./isoStringBody.js";
+export { formatHourDuration } from "./hourDurationString.js";
+export { canonicalInstantIntervals } from "./instantIntervalText.js";
+export { parseInstantNanoseconds } from "./instantNanoseconds.js";
+export { coalesceIntervalNanoseconds, parseIntervalNanoseconds, parseIntervalNanosecondsList, } from "./intervalNanoseconds.js";
 export { resolveDurationRelativeTo } from "./resolveDurationRelativeTo.js";
+export { formatUtcOffset, parseUtcOffsetNanoseconds } from "./utcOffsetString.js";
 export { ENGLISH_MONTH_NAMES, ENGLISH_WEEKDAY_NAMES, } from "./englishCalendarNames.js";
-export { dateFromEthiopicFamilyFields, ethiopicFamilyDateParts, formatEthiopicFamilyDate, isEthiopicFamilyCalendar, } from "./ethiopicFamilyCalendar.js";
+export { defaultFractionalDigits } from "./defaultFractionalDigits.js";
 export { getLocaleFirstDayOfWeek } from "./getLocaleFirstDayOfWeek.js";
-export { getLocaleMinimalDaysInFirstWeek } from "./getLocaleMinimalDaysInFirstWeek.js";
+export { resolveMinimalDaysInFirstWeek } from "./resolveMinimalDaysInFirstWeek.js";
 export { getLocaleWeekYearBounds } from "./getLocaleWeekYearBounds.js";
 export { getLocaleWeekendDays } from "./getLocaleWeekendDays.js";
-export { getStartOfZonedUnit, getUnitSpan } from "./intervalCountHelpers.js";
+export { getUnitSpan } from "./intervalCountHelpers.js";
+export { isObject, isOptionsArgument } from "./isObject.js";
 export { isValidAmount } from "./isValidAmount.js";
 export { joinDateTimeConnector } from "./joinDateTimeConnector.js";
 export { isValidDayOfWeek } from "./isValidDayOfWeek.js";
 export { monthGridWeekRow } from "./monthGridWeekRow.js";
 export { normalizeDateTime } from "./normalizeDateTime.js";
 export { DATE_PATTERN_FIELDS, DATE_TIME_PATTERN_FIELDS, parseValueWithPattern, TIME_PATTERN_FIELDS, } from "./patternToken.js";
+export { plainDateAdd } from "./plainDateAdd.js";
+export { plainDateUntil } from "./plainDateUntil.js";
 export { resolveDateTimeUnit } from "./resolveDateTimeUnit.js";
 export { resolveDurationUnit } from "./resolveDurationUnit.js";
 export { resolveOverflow } from "./resolveOverflow.js";
 export { resolveRelativeRounding } from "./resolveRelativeRounding.js";
+export { parseUnixEpochInterval, parseUnixEpochIntervalList, parseUnixEpochIntervalPair, parseUnixEpochValue, } from "./unixEpochValue.js";
+export { tileByUnit } from "./splitStep.js";
+export { countZonedBuckets, nextZonedBucketStart, type WeekStartDay, zonedUnitEnd, zonedUnitStart, } from "./zonedBucket.js";
+export { countZonedLocalDates } from "./zonedLocalDates.js";
+export { zonedDateTimeFrom } from "./zonedWallClock.js";
+export { durationCompare, durationRound, durationTotal, isCalendarDifferenceAcrossZones, plainUntilWithRounding, zonedUntil, } from "./zonedWallClockDifference.js";
+export { addToZoned, addToZonedDisambiguated, plainToZoned, roundZonedDateTime, subtractFromZoned, withZonedFields, zonedHoursInDay, zonedNextTransition, zonedStartOfDay, } from "./zonedWallClockOperations.js";
+export { zonelessCalendarDate } from "./zonelessCalendarDate.js";

package/dist/internal/index.js

@@ -1,34 +1,53 @@
-export { advanceBusinessDays } from "./advanceBusinessDays.js";
-export { adjustZonedBusinessDays } from "./adjustZonedBusinessDays.js";
 export { advanceToWeekday } from "./advanceToWeekday.js";
-export { calendarDateParts, formatCalendarDate, parseCalendarDateValue, } from "./calendarDateString.js";
-export { isCalendarSystem, temporalCalendarIds } from "./calendarSystemIds.js";
+export { parseCalendarDateValue } from "./calendarDateString.js";
+export { canonicalCalendarSystem, isCalendarSystem } from "./calendarSystemIds.js";
 export { parseCalendarDatePairForArithmetic } from "./calendarDatePairPolicy.js";
 export { parseCalendarZonedPairForArithmetic } from "./calendarZonedPairPolicy.js";
 export { calendarOfAllDateValues, calendarSystemOfDateValue, } from "./calendarValueOfDate.js";
 export { calendarOfAllZonedValues, calendarSystemOfZonedValue, } from "./calendarValueOfZoned.js";
 export { formatZonedInCalendar, parseCalendarZonedValue, } from "./calendarZonedString.js";
 export { cycleFieldValue } from "./cycleFieldValue.js";
+export { fiscalPeriodOfWeek, fiscalYearOf } from "./fiscalCalendar.js";
+export { floorDivide } from "./floorDivide.js";
+export { DOT_NET_TICKS_EPOCH_OFFSET, EXCEL_1900_EPOCH_NANOSECONDS, EXCEL_1900_PHANTOM_END_NANOSECONDS, EXCEL_1900_PRE_PHANTOM_EPOCH_NANOSECONDS, EXCEL_1904_EPOCH_NANOSECONDS, EXCEL_PHANTOM_SERIAL, FILE_TIME_EPOCH_OFFSET_TICKS, MAX_DOT_NET_TICKS, MAX_EXCEL_1900_SERIAL_EXCLUSIVE, MAX_EXCEL_1904_SERIAL_EXCLUSIVE, MAX_FILE_TIME, MILLISECONDS_PER_DAY, MIN_DOT_NET_TICKS, MIN_EXCEL_1900_SERIAL, MIN_EXCEL_1904_SERIAL, MIN_FILE_TIME, MIN_PG_MICROSECONDS, NANOSECONDS_PER_DAY, NANOSECONDS_PER_DAY_NUMBER, NANOSECONDS_PER_MICROSECOND, NANOSECONDS_PER_MILLISECOND, NANOSECONDS_PER_SECOND, NANOSECONDS_PER_TICK, NTP_EPOCH_OFFSET_NANOSECONDS, NTP_ERA_UNITS, NTP_UNITS_PER_SECOND, PG_EPOCH_OFFSET_MICROSECONDS, } from "./foreignEpochs.js";
+export { isValidEpochNanoseconds, MAX_EPOCH_NANOSECOND_DIGITS, } from "./epochNanoseconds.js";
 export { dateCycleFieldBounds } from "./dateCycleFieldBounds.js";
 export { timeCycleFieldBounds } from "./timeCycleFieldBounds.js";
 export { durationUntilString } from "./durationUntilString.js";
-export { calendarDateStringParts, formatDateInCalendar, } from "./formatDateInCalendar.js";
-export { hasCalendarAnnotation } from "./hasCalendarAnnotation.js";
+export { formatDateInCalendar } from "./formatDateInCalendar.js";
+export { halfOpenAbuts, halfOpenContainsPoint, halfOpenContainsSpan, halfOpenDifference, halfOpenIntersection, halfOpenMerge, halfOpenOverlap, halfOpenUnion, halfOpenXor, } from "./halfOpenIntervals.js";
+export { isoStringBody } from "./isoStringBody.js";
+export { formatHourDuration } from "./hourDurationString.js";
+export { canonicalInstantIntervals } from "./instantIntervalText.js";
+export { parseInstantNanoseconds } from "./instantNanoseconds.js";
+export { coalesceIntervalNanoseconds, parseIntervalNanoseconds, parseIntervalNanosecondsList, } from "./intervalNanoseconds.js";
 export { resolveDurationRelativeTo } from "./resolveDurationRelativeTo.js";
+export { formatUtcOffset, parseUtcOffsetNanoseconds } from "./utcOffsetString.js";
 export { ENGLISH_MONTH_NAMES, ENGLISH_WEEKDAY_NAMES, } from "./englishCalendarNames.js";
-export { dateFromEthiopicFamilyFields, ethiopicFamilyDateParts, formatEthiopicFamilyDate, isEthiopicFamilyCalendar, } from "./ethiopicFamilyCalendar.js";
+export { defaultFractionalDigits } from "./defaultFractionalDigits.js";
 export { getLocaleFirstDayOfWeek } from "./getLocaleFirstDayOfWeek.js";
-export { getLocaleMinimalDaysInFirstWeek } from "./getLocaleMinimalDaysInFirstWeek.js";
+export { resolveMinimalDaysInFirstWeek } from "./resolveMinimalDaysInFirstWeek.js";
 export { getLocaleWeekYearBounds } from "./getLocaleWeekYearBounds.js";
 export { getLocaleWeekendDays } from "./getLocaleWeekendDays.js";
-export { getStartOfZonedUnit, getUnitSpan } from "./intervalCountHelpers.js";
+export { getUnitSpan } from "./intervalCountHelpers.js";
+export { isObject, isOptionsArgument } from "./isObject.js";
 export { isValidAmount } from "./isValidAmount.js";
 export { joinDateTimeConnector } from "./joinDateTimeConnector.js";
 export { isValidDayOfWeek } from "./isValidDayOfWeek.js";
 export { monthGridWeekRow } from "./monthGridWeekRow.js";
 export { normalizeDateTime } from "./normalizeDateTime.js";
 export { DATE_PATTERN_FIELDS, DATE_TIME_PATTERN_FIELDS, parseValueWithPattern, TIME_PATTERN_FIELDS, } from "./patternToken.js";
+export { plainDateAdd } from "./plainDateAdd.js";
+export { plainDateUntil } from "./plainDateUntil.js";
 export { resolveDateTimeUnit } from "./resolveDateTimeUnit.js";
 export { resolveDurationUnit } from "./resolveDurationUnit.js";
 export { resolveOverflow } from "./resolveOverflow.js";
 export { resolveRelativeRounding } from "./resolveRelativeRounding.js";
+export { parseUnixEpochInterval, parseUnixEpochIntervalList, parseUnixEpochIntervalPair, parseUnixEpochValue, } from "./unixEpochValue.js";
+export { tileByUnit } from "./splitStep.js";
+export { countZonedBuckets, nextZonedBucketStart, zonedUnitEnd, zonedUnitStart, } from "./zonedBucket.js";
+export { countZonedLocalDates } from "./zonedLocalDates.js";
+export { zonedDateTimeFrom } from "./zonedWallClock.js";
+export { durationCompare, durationRound, durationTotal, isCalendarDifferenceAcrossZones, plainUntilWithRounding, zonedUntil, } from "./zonedWallClockDifference.js";
+export { addToZoned, addToZonedDisambiguated, plainToZoned, roundZonedDateTime, subtractFromZoned, withZonedFields, zonedHoursInDay, zonedNextTransition, zonedStartOfDay, } from "./zonedWallClockOperations.js";
+export { zonelessCalendarDate } from "./zonelessCalendarDate.js";

package/dist/internal/instantFormatOptions.d.ts

@@ -0,0 +1,43 @@
+import type { Temporal } from "@js-temporal/polyfill";
+type Options = Intl.DateTimeFormatOptions;
+/**
+ * Resolve caller options into runtime `Intl.DateTimeFormat` options that
+ * format an exact time in `timeZone`.
+ *
+ * - Returns `null` when the caller passed a `timeZone` option: the value is
+ *   formatted in its own zone, and `Temporal.ZonedDateTime#toLocaleString`
+ *   throws a TypeError for one (CreateDateTimeFormat with
+ *   toLocaleStringTimeZone).
+ * - With no date or time field and no `dateStyle`/`timeStyle`, year, month,
+ *   day, hour, minute and second default to `"numeric"`. With `defaults`
+ *   `"zoned-date-time"` (ZonedDateTime#toLocaleString) `timeZoneName` also
+ *   defaults to `"short"`; with `"all"` (an Instant) it does not.
+ *
+ * @param options caller's `Intl.DateTimeFormatOptions`
+ * @param timeZone the zone the value is formatted in
+ * @param defaults GetDateTimeFormat defaults: `"zoned-date-time"` or `"all"`
+ * @returns runtime options in `timeZone`, or `null` for a `timeZone` option
+ */
+export declare function instantFormatOptions(options: Options, timeZone: string, defaults: "zoned-date-time" | "all"): Options | null;
+/**
+ * Format an exact time as text, either as its wall clock (a PlainDateTime) or
+ * as a ZonedDateTime with its zone, through the runtime's
+ * `Intl.DateTimeFormat`. Shared by `formatUtc` and `formatUnix`.
+ *
+ * - The wall-clock path uses {@link plainDateTimeFormatOptions}
+ *   (GetDateTimeFormat ~any~, ~all~, ~relevant~): `timeZoneName` is not
+ *   inherited.
+ * - The zoned path uses {@link instantFormatOptions} with
+ *   `"zoned-date-time"` defaults.
+ * - `options` must not carry a `timeZone`; the zone comes from
+ *   `zonedDateTime`. Constructing with `options` first surfaces the TypeError
+ *   or RangeError Intl.DateTimeFormat raises for invalid ones.
+ *
+ * @param zonedDateTime the value in the zone it is rendered in
+ * @param locale BCP 47 locale, or `undefined` for the runtime default
+ * @param options caller's `Intl.DateTimeFormatOptions` without `timeZone`
+ * @param includeTimeZoneName `true` for the zoned path
+ * @returns the formatted text, not yet normalised
+ */
+export declare function formatWallClockOrZoned(zonedDateTime: Temporal.ZonedDateTime, locale: string | string[] | undefined, options: Options, includeTimeZoneName: boolean): string;
+export {};

package/dist/internal/instantFormatOptions.js

@@ -0,0 +1,99 @@
+// Option resolution for formatting an exact time (a ZonedDateTime, or an
+// Instant in a given zone) through the runtime's `Intl.DateTimeFormat`. The
+// rules are the Temporal proposal's ECMA-402 amendments: CreateDateTimeFormat
+// and GetDateTimeFormat with required ~any~ and inherit ~all~, so every caller
+// field, including `era` and `timeZoneName`, is passed on unchanged.
+import { plainDateTimeFormatOptions } from "./plainFormatOptions.js";
+// GetDateTimeFormat requiredOptions for ~any~. `era` and `timeZoneName` are
+// deliberately absent: neither suppresses the defaults.
+const REQUIRED_FIELDS = [
+    "weekday",
+    "year",
+    "month",
+    "day",
+    "dayPeriod",
+    "hour",
+    "minute",
+    "second",
+    "fractionalSecondDigits",
+];
+const DEFAULT_FIELDS = {
+    year: "numeric",
+    month: "numeric",
+    day: "numeric",
+    hour: "numeric",
+    minute: "numeric",
+    second: "numeric",
+};
+/**
+ * Resolve caller options into runtime `Intl.DateTimeFormat` options that
+ * format an exact time in `timeZone`.
+ *
+ * - Returns `null` when the caller passed a `timeZone` option: the value is
+ *   formatted in its own zone, and `Temporal.ZonedDateTime#toLocaleString`
+ *   throws a TypeError for one (CreateDateTimeFormat with
+ *   toLocaleStringTimeZone).
+ * - With no date or time field and no `dateStyle`/`timeStyle`, year, month,
+ *   day, hour, minute and second default to `"numeric"`. With `defaults`
+ *   `"zoned-date-time"` (ZonedDateTime#toLocaleString) `timeZoneName` also
+ *   defaults to `"short"`; with `"all"` (an Instant) it does not.
+ *
+ * @param options caller's `Intl.DateTimeFormatOptions`
+ * @param timeZone the zone the value is formatted in
+ * @param defaults GetDateTimeFormat defaults: `"zoned-date-time"` or `"all"`
+ * @returns runtime options in `timeZone`, or `null` for a `timeZone` option
+ */
+export function instantFormatOptions(options, timeZone, defaults) {
+    if (options.timeZone !== undefined)
+        return null;
+    const needDefaults = options.dateStyle === undefined &&
+        options.timeStyle === undefined &&
+        REQUIRED_FIELDS.every((field) => options[field] === undefined);
+    if (!needDefaults)
+        return { ...options, timeZone };
+    // Defaults spread after the caller's options: needDefaults guarantees every
+    // default field is undefined there, even when present as a key.
+    return {
+        ...options,
+        ...DEFAULT_FIELDS,
+        ...(defaults === "zoned-date-time"
+            ? {
+                timeZoneName: options.timeZoneName === undefined ? "short" : options.timeZoneName,
+            }
+            : {}),
+        timeZone,
+    };
+}
+/**
+ * Format an exact time as text, either as its wall clock (a PlainDateTime) or
+ * as a ZonedDateTime with its zone, through the runtime's
+ * `Intl.DateTimeFormat`. Shared by `formatUtc` and `formatUnix`.
+ *
+ * - The wall-clock path uses {@link plainDateTimeFormatOptions}
+ *   (GetDateTimeFormat ~any~, ~all~, ~relevant~): `timeZoneName` is not
+ *   inherited.
+ * - The zoned path uses {@link instantFormatOptions} with
+ *   `"zoned-date-time"` defaults.
+ * - `options` must not carry a `timeZone`; the zone comes from
+ *   `zonedDateTime`. Constructing with `options` first surfaces the TypeError
+ *   or RangeError Intl.DateTimeFormat raises for invalid ones.
+ *
+ * @param zonedDateTime the value in the zone it is rendered in
+ * @param locale BCP 47 locale, or `undefined` for the runtime default
+ * @param options caller's `Intl.DateTimeFormatOptions` without `timeZone`
+ * @param includeTimeZoneName `true` for the zoned path
+ * @returns the formatted text, not yet normalised
+ */
+export function formatWallClockOrZoned(zonedDateTime, locale, options, includeTimeZoneName) {
+    new Intl.DateTimeFormat(locale, options);
+    if (includeTimeZoneName) {
+        const resolved = instantFormatOptions(options, zonedDateTime.timeZoneId, "zoned-date-time");
+        return resolved === null
+            ? ""
+            : new Intl.DateTimeFormat(locale, resolved).format(zonedDateTime.epochMilliseconds);
+    }
+    const wallClockMilliseconds = zonedDateTime
+        .toPlainDateTime()
+        .toZonedDateTime("UTC").epochMilliseconds;
+    return new Intl.DateTimeFormat(locale, plainDateTimeFormatOptions(options)).format(wallClockMilliseconds);
+}

package/dist/internal/instantIntervalText.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Re-serialise instant intervals to `Temporal.Instant.prototype.toString()` spelling.
+ *
+ * The CORE-6 `interval/` functions echo the caller's strings; the positional `utc/interval/`
+ * functions that delegate to them return canonical `Z` strings instead (CORE-8 half-open decisions of record:
+ * outputs stay re-serialised), so tie-breaks between spellings of one instant never surface.
+ *
+ * - Returns `null` if any string fails to parse (callers validate first, so only a throwing
+ *   `Temporal.Instant.from` reaches this).
+ *
+ * @example canonicalInstantIntervals([{ start: "2024-01-01T09:00:00.000Z", end: "2024-01-01T12:00Z" }]) // [{ start: "2024-01-01T09:00:00Z", end: "2024-01-01T12:00:00Z" }]
+ * @example canonicalInstantIntervals([]) // []
+ */
+export declare function canonicalInstantIntervals(intervals: ReadonlyArray<{
+    start: string;
+    end: string;
+}>): Array<{
+    start: string;
+    end: string;
+}> | null;

package/dist/internal/instantIntervalText.js

@@ -0,0 +1,25 @@
+import { Temporal } from "@js-temporal/polyfill";
+/**
+ * Re-serialise instant intervals to `Temporal.Instant.prototype.toString()` spelling.
+ *
+ * The CORE-6 `interval/` functions echo the caller's strings; the positional `utc/interval/`
+ * functions that delegate to them return canonical `Z` strings instead (CORE-8 half-open decisions of record:
+ * outputs stay re-serialised), so tie-breaks between spellings of one instant never surface.
+ *
+ * - Returns `null` if any string fails to parse (callers validate first, so only a throwing
+ *   `Temporal.Instant.from` reaches this).
+ *
+ * @example canonicalInstantIntervals([{ start: "2024-01-01T09:00:00.000Z", end: "2024-01-01T12:00Z" }]) // [{ start: "2024-01-01T09:00:00Z", end: "2024-01-01T12:00:00Z" }]
+ * @example canonicalInstantIntervals([]) // []
+ */
+export function canonicalInstantIntervals(intervals) {
+    try {
+        return intervals.map(({ start, end }) => ({
+            start: Temporal.Instant.from(start).toString(),
+            end: Temporal.Instant.from(end).toString(),
+        }));
+    }
+    catch {
+        return null;
+    }
+}

package/dist/internal/instantNanoseconds.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Parse an ISO 8601 instant string to epoch nanoseconds, or `null` when it is not one.
+ *
+ * The single definition of "an instant string GMT accepts": the RFC 9557 instant grammar
+ * `Temporal.Instant.from` parses, restricted to ISO 8601 extended format before the first `[`
+ * (`instantBody`: `<date>T<time>`, then `Z` or `±HH:MM[:SS[.fraction]]`), minus
+ * leap seconds (which Temporal clamps rather than rejects). Basic format, a space or lower-case
+ * `t` separator, a lower-case `z` and an hour-only time or offset are rejected. Annotations are read as Temporal reads them (proposal-temporal
+ * `ParseISODateTime`, RFC 9557 §3.3): a time zone, calendar (`[u-ca=hebrew]`) or elective
+ * (`[foo=bar]`) annotation is ignored, because an instant has neither zone nor calendar, and an
+ * unknown critical one (`[!foo=bar]`) is rejected. Callers layer their own sentinel on top —
+ * `toNanoseconds` returns `0n`, `spanNs` returns `null` — so the parse result stays unambiguous
+ * here.
+ *
+ * @param value candidate ISO 8601 instant string
+ * @returns nanoseconds since the Unix epoch, or null when `value` is not a valid instant
+ *
+ * @example parseInstantNanoseconds("1970-01-01T00:00:00Z") // 0n
+ * @example parseInstantNanoseconds("2016-12-31T23:59:60Z") // null — leap second
+ * @example parseInstantNanoseconds("2024-03-10T12:00:00") // null — no offset designator
+ * @example parseInstantNanoseconds("20240310T120000Z") // null — basic format
+ * @example parseInstantNanoseconds("2024-03-10T12:00:00z") // null — lower-case z
+ * @example parseInstantNanoseconds("1970-01-01T00:00:00Z[u-ca=hebrew]") // 0n — calendar annotation ignored
+ */
+export declare function parseInstantNanoseconds(value: string): bigint | null;

package/dist/internal/instantNanoseconds.js

@@ -0,0 +1,41 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { instantLeapSecond } from "../regex/leap-second.js";
+import { hasInstantShape } from "./isoStringBody.js";
+/**
+ * Parse an ISO 8601 instant string to epoch nanoseconds, or `null` when it is not one.
+ *
+ * The single definition of "an instant string GMT accepts": the RFC 9557 instant grammar
+ * `Temporal.Instant.from` parses, restricted to ISO 8601 extended format before the first `[`
+ * (`instantBody`: `<date>T<time>`, then `Z` or `±HH:MM[:SS[.fraction]]`), minus
+ * leap seconds (which Temporal clamps rather than rejects). Basic format, a space or lower-case
+ * `t` separator, a lower-case `z` and an hour-only time or offset are rejected. Annotations are read as Temporal reads them (proposal-temporal
+ * `ParseISODateTime`, RFC 9557 §3.3): a time zone, calendar (`[u-ca=hebrew]`) or elective
+ * (`[foo=bar]`) annotation is ignored, because an instant has neither zone nor calendar, and an
+ * unknown critical one (`[!foo=bar]`) is rejected. Callers layer their own sentinel on top —
+ * `toNanoseconds` returns `0n`, `spanNs` returns `null` — so the parse result stays unambiguous
+ * here.
+ *
+ * @param value candidate ISO 8601 instant string
+ * @returns nanoseconds since the Unix epoch, or null when `value` is not a valid instant
+ *
+ * @example parseInstantNanoseconds("1970-01-01T00:00:00Z") // 0n
+ * @example parseInstantNanoseconds("2016-12-31T23:59:60Z") // null — leap second
+ * @example parseInstantNanoseconds("2024-03-10T12:00:00") // null — no offset designator
+ * @example parseInstantNanoseconds("20240310T120000Z") // null — basic format
+ * @example parseInstantNanoseconds("2024-03-10T12:00:00z") // null — lower-case z
+ * @example parseInstantNanoseconds("1970-01-01T00:00:00Z[u-ca=hebrew]") // 0n — calendar annotation ignored
+ */
+export function parseInstantNanoseconds(value) {
+    if (typeof value !== "string") {
+        return null;
+    }
+    if (instantLeapSecond.test(value) || !hasInstantShape(value)) {
+        return null;
+    }
+    try {
+        return Temporal.Instant.from(value).epochNanoseconds;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/internal/intervalCountHelpers.d.ts

@@ -1,18 +1,24 @@
 import type { Temporal } from "@js-temporal/polyfill";
 import type { DateTimeUnit } from "../types/index.js";
 /**
- * Return the start of the specified date-time `unit` for a `Temporal.ZonedDateTime`.
+ * Singular DateTimeUnit to its `Temporal.Duration` field name.
  *
- * - Always uses Monday as the week start (consistent with `startOfZoned` semantics).
- * - Day-and-below units truncate by instant via `round({ roundingMode: "trunc" })`, which
- *   resolves DST correctly — a local day whose midnight is skipped starts at 01:00.
- * - Does NOT validate the unit — caller ensures it is a DateTimeUnit.
- *
- * @param source Temporal.ZonedDateTime to truncate
- * @param unit DateTimeUnit to truncate to
- * @returns Temporal.ZonedDateTime at the start of the specified unit
+ * Example lookups:
+ * - DURATION_FIELD_BY_UNIT.day => "days"
+ * - DURATION_FIELD_BY_UNIT.nanosecond => "nanoseconds"
  */
-export declare function getStartOfZonedUnit(source: Temporal.ZonedDateTime, unit: DateTimeUnit): Temporal.ZonedDateTime;
+export declare const DURATION_FIELD_BY_UNIT: {
+    readonly year: "years";
+    readonly month: "months";
+    readonly week: "weeks";
+    readonly day: "days";
+    readonly hour: "hours";
+    readonly minute: "minutes";
+    readonly second: "seconds";
+    readonly millisecond: "milliseconds";
+    readonly microsecond: "microseconds";
+    readonly nanosecond: "nanoseconds";
+};
 /**
  * Extract the whole-unit span from a `Temporal.Duration` measured with `largestUnit: unit`.
  *

package/dist/internal/intervalCountHelpers.js

@@ -5,7 +5,7 @@
  * - DURATION_FIELD_BY_UNIT.day => "days"
  * - DURATION_FIELD_BY_UNIT.nanosecond => "nanoseconds"
  */
-const DURATION_FIELD_BY_UNIT = {
+export const DURATION_FIELD_BY_UNIT = {
     year: "years",
     month: "months",
     week: "weeks",
@@ -17,36 +17,6 @@ const DURATION_FIELD_BY_UNIT = {
     microsecond: "microseconds",
     nanosecond: "nanoseconds",
 };
-/**
- * Return the start of the specified date-time `unit` for a `Temporal.ZonedDateTime`.
- *
- * - Always uses Monday as the week start (consistent with `startOfZoned` semantics).
- * - Day-and-below units truncate by instant via `round({ roundingMode: "trunc" })`, which
- *   resolves DST correctly — a local day whose midnight is skipped starts at 01:00.
- * - Does NOT validate the unit — caller ensures it is a DateTimeUnit.
- *
- * @param source Temporal.ZonedDateTime to truncate
- * @param unit DateTimeUnit to truncate to
- * @returns Temporal.ZonedDateTime at the start of the specified unit
- */
-export function getStartOfZonedUnit(source, unit) {
-    switch (unit) {
-        case "year":
-            return source
-                .with({ month: 1, day: 1 })
-                .round({ smallestUnit: "day", roundingMode: "trunc" });
-        case "month":
-            return source
-                .with({ day: 1 })
-                .round({ smallestUnit: "day", roundingMode: "trunc" });
-        case "week":
-            return source
-                .subtract({ days: source.dayOfWeek - 1 })
-                .round({ smallestUnit: "day", roundingMode: "trunc" });
-        default:
-            return source.round({ smallestUnit: unit, roundingMode: "trunc" });
-    }
-}
 /**
  * Extract the whole-unit span from a `Temporal.Duration` measured with `largestUnit: unit`.
  *

package/dist/internal/intervalNanoseconds.d.ts

@@ -0,0 +1,47 @@
+/** An `Interval` parsed once: bigint epoch nanoseconds plus the exact strings they came from. */
+export interface IntervalNanoseconds {
+    start: bigint;
+    end: bigint;
+    startText: string;
+    endText: string;
+}
+/**
+ * Parse a candidate `Interval` to epoch nanoseconds, or `null` when it is not one.
+ *
+ * - Any non-null object with ISO 8601 instant strings `start` ≤ `end` (by instant) is accepted;
+ *   extra keys are ignored (GMT rule: the type is structural).
+ * - Each endpoint is read exactly once, so the validated text is the text callers echo.
+ *
+ * @param value candidate `{ start, end }` record
+ * @returns the parsed record, or null when `value` is not a valid `Interval`
+ *
+ * @example parseIntervalNanoseconds({ start: "1970-01-01T00:00:00Z", end: "1970-01-01T00:00:00.000000001Z" }) // { start: 0n, end: 1n, startText: "1970-01-01T00:00:00Z", endText: "1970-01-01T00:00:00.000000001Z" }
+ * @example parseIntervalNanoseconds({ start: "1970-01-01T00:00:01Z", end: "1970-01-01T00:00:00Z" }) // null — inverted
+ */
+export declare function parseIntervalNanoseconds(value: unknown): IntervalNanoseconds | null;
+/**
+ * Parse a list of candidate `Interval`s, all-or-nothing.
+ *
+ * @param values candidate array of `{ start, end }` records
+ * @returns the parsed records in input order, or null when `values` is not an array or any element is invalid
+ *
+ * @example parseIntervalNanosecondsList([]) // []
+ * @example parseIntervalNanosecondsList([null]) // null
+ */
+export declare function parseIntervalNanosecondsList(values: unknown): IntervalNanoseconds[] | null;
+/**
+ * Sweep parsed intervals into sorted, disjoint, non-touching, non-empty runs.
+ *
+ * - Touching records coalesce (`start <= run.end`); a 1 ns gap does not.
+ * - Equal starts keep input order (stable sort), so a run keeps its first start text; the first
+ *   record to reach the run's latest end keeps its end text (GMT rule: first wins ties).
+ * - Empty records that touch or fall inside a run are absorbed; a stranded one is dropped.
+ * - Runs are copies; the input records are never mutated.
+ *
+ * @param records parsed intervals, in any order
+ * @returns coalesced runs sorted by start
+ *
+ * @example coalesceIntervalNanoseconds([{ start: 3n, end: 5n, startText: "c", endText: "e" }, { start: 1n, end: 3n, startText: "a", endText: "c" }]) // [{ start: 1n, end: 5n, startText: "a", endText: "e" }]
+ * @example coalesceIntervalNanoseconds([{ start: 4n, end: 4n, startText: "d", endText: "d" }]) // []
+ */
+export declare function coalesceIntervalNanoseconds(records: readonly IntervalNanoseconds[]): IntervalNanoseconds[];