@northguild/gmt 1.17.0 → 1.19.0

package/dist/internal/exactMoment.js

@@ -0,0 +1,114 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidZonedDateTime } from "../zoned/validate/isValidZonedDateTime.js";
+import { parseInstantNanoseconds } from "./instantNanoseconds.js";
+import { EXTENDED_UTC_OFFSET, TIME_ZONE_ANNOTATION } from "./isoStringBody.js";
+import { wallClockAtOffset } from "./wallClockAtOffset.js";
+import { utcOffsetStringNanoseconds, zonedDateTimeFrom, } from "./zonedWallClock.js";
+/**
+ * Trailing `Z` or extended offset of an instant string, before any annotation. The offset grammar
+ * is `isValidInstant`'s own (`EXTENDED_UTC_OFFSET`), so every offset it accepts, `,` fractions
+ * included, is captured as written.
+ */
+const trailingOffset = new RegExp(`(Z|${EXTENDED_UTC_OFFSET})(?:\\[[^\\]]*\\])*$`);
+/**
+ * A time-zone annotation anywhere in the string (`TIME_ZONE_ANNOTATION`). Every `key=value`
+ * bracket is a tagged annotation, which the instant parse already decides.
+ */
+const zoneAnnotation = new RegExp(TIME_ZONE_ANNOTATION);
+/**
+ * Read an exact moment the way `transitTime` reads a departure, or `null`.
+ *
+ * - A zoned string (`…-04:00[America/New_York]`) is read through its bracket, which must name a
+ *   real zone that agrees with the offset, as `isValidZonedDateTime` requires. An offset written
+ *   to the minute agrees when it is the zone's sub-minute offset rounded (TC39
+ *   `ToTemporalZonedDateTime`, match-minutes), which is how `writeExactMoment` writes one.
+ * - A wall time with a bracket and no offset is read in that zone with the `"compatible"`
+ *   disambiguation policy (`context/reference/LOCAL_TIME_RESOLUTION.md`): an **ambiguous** wall
+ *   time, a fall-back hour the clock ran through twice, resolves to the **earlier** instant
+ *   (`2024-11-03T01:30:00[America/New_York]` is `01:30-04:00`), and a **nonexistent** one, a
+ *   spring-forward hour the clock skipped, to the **later** instant
+ *   (`2024-03-10T02:30:00[America/New_York]` is `03:30-04:00`). A caller that must not guess
+ *   refuses the offset-less form before calling, as `nextDeparture` does.
+ * - A string that names a zone the zoned read rejects is `null`; it never falls back to its
+ *   offset. That includes a zoned string whose local date is −271821-04-19, which
+ *   `Temporal.ZonedDateTime.from` refuses although its instant is in range.
+ * - Otherwise an instant (`Z` or an offset) as `parseInstantNanoseconds` reads it: calendar and
+ *   elective annotations are ignored and a critical unknown one is rejected. Its offset text is
+ *   kept exactly as written, sub-minute and `,` fractions included.
+ *
+ * @param value candidate zoned datetime or instant string
+ * @returns the moment's epoch nanoseconds and notation, or null on invalid input
+ *
+ * @example readExactMoment("2024-06-15T10:00:00+09:00") // { nanoseconds: 1718413200000000000n, notation: { kind: "offset", offset: "+09:00" } }
+ * @example readExactMoment("2024-06-15T10:00:00Z[Not/AZone]") // null
+ * @example readExactMoment("2024-03-10T02:30:00[America/New_York]") // { nanoseconds: 1710055800000000000n, notation: { kind: "zone", timeZone: "America/New_York" } } (nonexistent: the later instant, 03:30-04:00)
+ */
+export function readExactMoment(value) {
+    if (typeof value !== "string") {
+        return null;
+    }
+    try {
+        if (isValidZonedDateTime(value)) {
+            const zoned = zonedDateTimeFrom(value);
+            return {
+                nanoseconds: zoned.epochNanoseconds,
+                notation: { kind: "zone", timeZone: zoned.timeZoneId },
+            };
+        }
+        if (zoneAnnotation.test(value)) {
+            return null;
+        }
+        const nanoseconds = parseInstantNanoseconds(value);
+        if (nanoseconds === null) {
+            return null;
+        }
+        const offset = trailingOffset.exec(value)?.[1] ?? "Z";
+        return {
+            nanoseconds,
+            notation: offset === "Z" ? { kind: "utc" } : { kind: "offset", offset },
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Write epoch nanoseconds the way a moment was written: in its zone, at its offset text, or as a
+ * `Z` instant. `""` when the nanoseconds leave the instant range (±8.64e21 ns).
+ *
+ * - A zone notation is written as Temporal writes a `ZonedDateTime`: the offset in force at that
+ *   instant, rounded to the minute (`-00:45` for Monrovia's −00:44:30), then the bracket.
+ *   `readExactMoment` and `parseInstantNanoseconds` read that string back as the same instant,
+ *   with two exceptions, both Temporal's own. A wall time repeated inside a sub-minute offset
+ *   change reads as its first pass, in both readers (`parseInstantNanoseconds` states the
+ *   rule). And `readExactMoment`, a zoned read, refuses a string whose local date is
+ *   −271821-04-19 (`CheckISODaysRange` in `Temporal.ZonedDateTime.from`): the string written
+ *   for the first hours of the instant range in a zone west of Greenwich reads as `null` there,
+ *   and as its instant in `parseInstantNanoseconds`
+ *   (`context/domination/js-temporal-polyfill-bugs.md` § J).
+ * - An offset notation keeps its text as written. The wall clock is shifted, never the instant
+ *   (`wallClockAtOffset`), so the last hours of the range still write at a positive offset.
+ *
+ * @param nanoseconds epoch nanoseconds of the moment to write
+ * @param notation how to write it, from `readExactMoment`
+ * @returns the moment as a zoned, offset or `Z` string, or "" when it is out of range
+ *
+ * @example writeExactMoment(0n, { kind: "offset", offset: "+09:00" }) // "1970-01-01T09:00:00+09:00"
+ * @example writeExactMoment(0n, { kind: "zone", timeZone: "UTC" }) // "1970-01-01T00:00:00+00:00[UTC]"
+ */
+export function writeExactMoment(nanoseconds, notation) {
+    try {
+        const instant = Temporal.Instant.fromEpochNanoseconds(nanoseconds);
+        if (notation.kind === "zone") {
+            return instant.toZonedDateTimeISO(notation.timeZone).toString();
+        }
+        if (notation.kind === "utc") {
+            return instant.toString();
+        }
+        const wall = wallClockAtOffset(instant, utcOffsetStringNanoseconds(notation.offset));
+        return `${wall.toString()}${notation.offset}`;
+    }
+    catch {
+        return "";
+    }
+}

package/dist/internal/fiscalCalendar.d.ts

@@ -10,9 +10,10 @@ import type { FiscalPattern } from "../types/index.js";
  * off the result.
  *
  * - The month-day is moved into `year` with Temporal's `overflow: "constrain"`, so a
- *   February 29 anchor targets February 28 in a common year before the weekday shift. A
- *   "month-end" rule (the 26 CFR 1.441-2 style, "the last Saturday of February") would
- *   instead put a February 28 anchor on February 29 in a leap year; this does not.
+ *   February 29 anchor targets February 28 in a common year before the weekday shift. A rule
+ *   tied to the end of a month ("the last Saturday of February", or the Saturday nearest the
+ *   month's last day) would instead put a February 28 anchor on February 29 in a leap year;
+ *   this does not.
  */
 export declare function fiscalYearEndIn(anchor: Temporal.PlainDate, year: number): Temporal.PlainDate;
 /**

package/dist/internal/fiscalCalendar.js

@@ -32,9 +32,10 @@ const NEAREST_WEEKDAY_RADIUS = 3;
  * off the result.
  *
  * - The month-day is moved into `year` with Temporal's `overflow: "constrain"`, so a
- *   February 29 anchor targets February 28 in a common year before the weekday shift. A
- *   "month-end" rule (the 26 CFR 1.441-2 style, "the last Saturday of February") would
- *   instead put a February 28 anchor on February 29 in a leap year; this does not.
+ *   February 29 anchor targets February 28 in a common year before the weekday shift. A rule
+ *   tied to the end of a month ("the last Saturday of February", or the Saturday nearest the
+ *   month's last day) would instead put a February 28 anchor on February 29 in a leap year;
+ *   this does not.
  */
 export function fiscalYearEndIn(anchor, year) {
     const target = anchor.with({ year }, { overflow: "constrain" });

package/dist/internal/formatCalendarDays.d.ts

@@ -13,7 +13,7 @@ import type { Temporal } from "@js-temporal/polyfill";
  * @example formatCalendarDays(1, 1710685800000, "UTC", "en-US", "short") // "tomorrow at 2:30 PM"
  * @example formatCalendarDays(-9, 1710685800000, "UTC", "en-US", "short") // "March 17, 2024 at 2:30 PM"
  */
-export declare function formatCalendarDays(diffDays: number, epochMilliseconds: number, timeZone: string, locale: string | string[] | undefined, timeStyle: "short" | "medium" | "full"): string;
+export declare function formatCalendarDays(diffDays: number, epochMilliseconds: number, timeZone: string, locale: string | string[] | undefined, timeStyle: "short" | "medium" | "long" | "full"): string;
 /**
  * `formatCalendarDays` for two instants, counting calendar days between their dates in `timeZone`.
  *
@@ -25,4 +25,4 @@ export declare function formatCalendarDays(diffDays: number, epochMilliseconds:
  * @returns the phrase; throws where Temporal or `Intl` throws
  * @example formatCalendarInstants(Temporal.Instant.from("2024-03-17T14:30:00Z"), Temporal.Instant.from("2024-03-16T09:00:00Z"), "UTC", "en-US", "short") // "tomorrow at 2:30 PM"
  */
-export declare function formatCalendarInstants(target: Temporal.Instant, reference: Temporal.Instant, timeZone: string, locale: string | string[] | undefined, timeStyle: "short" | "medium" | "full"): string;
+export declare function formatCalendarInstants(target: Temporal.Instant, reference: Temporal.Instant, timeZone: string, locale: string | string[] | undefined, timeStyle: "short" | "medium" | "long" | "full"): string;

package/dist/internal/formatRelativeDuration.d.ts

@@ -23,5 +23,25 @@ export interface RelativeDurationFormatOptions {
  * @example formatRelativeDuration(Temporal.Duration.from({ hours: 36 }), "en-US", { largestUnit: "hour" }, () => 0) // "in 36 hours"
  * @example formatRelativeDuration(Temporal.Duration.from({ days: 400 }), "en-US", {}, () => 1) // "next year" (month/year totals come from calendarTotal)
  */
-export declare function formatRelativeDuration(diff: Temporal.Duration, locale: string | string[] | undefined, options: RelativeDurationFormatOptions, calendarTotal: (unit: RelativeUnitName) => number): string;
+export declare function formatRelativeDuration(diff: Temporal.Duration, locale: string | string[] | undefined, options: RelativeDurationFormatOptions, calendarTotal: (unit: RelativeUnit) => number): string;
+/**
+ * Round a distance to a whole number of `unit` and render it with `Intl.RelativeTimeFormat`. The
+ * shared last step of every `formatRelative*` function.
+ *
+ * - `numeric` and `style` are read here, once each (GetOption); `roundingMethod` is passed in
+ *   because the caller has already read it.
+ *
+ * @param total the signed fractional distance in `unit`
+ * @param unit the singular unit the distance is written in
+ * @param locale BCP 47 locale(s) passed through to `Intl.RelativeTimeFormat`
+ * @param options the caller's options, read for `numeric` (default `"auto"`) and `style`
+ *   (default `"long"`)
+ * @param roundingMethod the caller's `roundingMethod`, `undefined` for the default `"round"`
+ * @returns the formatted phrase; throws where `Intl` throws or the rounding method is invalid, for
+ *   the caller's sentinel
+ * @example formatRelativeAmount(-1.5, "hour", "en-US", {}, "floor") // "2 hours ago"
+ * @example formatRelativeAmount(1, "day", "en-US", { numeric: "always" }, undefined) // "in 1 day"
+ * @example formatRelativeAmount(1, "day", "en-US", { style: "wide" as never }, undefined) // throws RangeError
+ */
+export declare function formatRelativeAmount(total: number, unit: RelativeUnit, locale: string | string[] | undefined, options: Pick<RelativeDurationFormatOptions, "numeric" | "style">, roundingMethod: RelativeRoundingMethod | undefined): string;
 export {};

package/dist/internal/formatRelativeDuration.js

@@ -1,5 +1,18 @@
 import { normalizeDateTime } from "./normalizeDateTime.js";
 import { resolveRelativeRounding } from "./resolveRelativeRounding.js";
+import { optionOrDefault } from "./optionOrDefault.js";
+import { resolveRelativeUnit } from "./resolveRelativeUnit.js";
+// The units of the seven-unit functions: Temporal's datetime unit group down to the second, less
+// the sub-second units, which Intl.RelativeTimeFormat does not have.
+const RELATIVE_UNITS = [
+    "year",
+    "month",
+    "week",
+    "day",
+    "hour",
+    "minute",
+    "second",
+];
 // Seconds up to a day, then formatRelativeDate's day thresholds (7, 28 and 365 days).
 const SECONDS_PER_DAY = 86_400;
 const AUTO_UNITS = [
@@ -26,20 +39,47 @@ const AUTO_UNITS = [
  * @example formatRelativeDuration(Temporal.Duration.from({ days: 400 }), "en-US", {}, () => 1) // "next year" (month/year totals come from calendarTotal)
  */
 export function formatRelativeDuration(diff, locale, options, calendarTotal) {
+    // Each option is read once (GetOption), and largestUnit is validated before anything is measured.
+    const forcedUnit = resolveRelativeUnit(options.largestUnit, RELATIVE_UNITS);
+    const roundingMethod = options.roundingMethod;
     const absSeconds = Math.abs(diff.total("second"));
-    const unit = options.largestUnit === undefined
+    const unit = forcedUnit === undefined
         ? (AUTO_UNITS.find((t) => absSeconds < t.maxSeconds)?.unit ?? "year")
-        : options.largestUnit;
-    let amount;
+        : forcedUnit;
+    let total;
     try {
-        amount = resolveRelativeRounding(diff.total(unit), options.roundingMethod);
+        total = diff.total(unit);
     }
     catch {
         // month/year are calendrical and need a relativeTo anchor.
-        amount = resolveRelativeRounding(calendarTotal(unit), options.roundingMethod);
+        total = calendarTotal(unit);
     }
+    // Outside the retry: an invalid roundingMethod throws once, straight to the caller's sentinel.
+    return formatRelativeAmount(total, unit, locale, options, roundingMethod);
+}
+/**
+ * Round a distance to a whole number of `unit` and render it with `Intl.RelativeTimeFormat`. The
+ * shared last step of every `formatRelative*` function.
+ *
+ * - `numeric` and `style` are read here, once each (GetOption); `roundingMethod` is passed in
+ *   because the caller has already read it.
+ *
+ * @param total the signed fractional distance in `unit`
+ * @param unit the singular unit the distance is written in
+ * @param locale BCP 47 locale(s) passed through to `Intl.RelativeTimeFormat`
+ * @param options the caller's options, read for `numeric` (default `"auto"`) and `style`
+ *   (default `"long"`)
+ * @param roundingMethod the caller's `roundingMethod`, `undefined` for the default `"round"`
+ * @returns the formatted phrase; throws where `Intl` throws or the rounding method is invalid, for
+ *   the caller's sentinel
+ * @example formatRelativeAmount(-1.5, "hour", "en-US", {}, "floor") // "2 hours ago"
+ * @example formatRelativeAmount(1, "day", "en-US", { numeric: "always" }, undefined) // "in 1 day"
+ * @example formatRelativeAmount(1, "day", "en-US", { style: "wide" as never }, undefined) // throws RangeError
+ */
+export function formatRelativeAmount(total, unit, locale, options, roundingMethod) {
+    const amount = resolveRelativeRounding(total, roundingMethod);
     return normalizeDateTime(new Intl.RelativeTimeFormat(locale, {
-        numeric: options.numeric === undefined ? "auto" : options.numeric,
-        style: options.style === undefined ? "long" : options.style,
+        numeric: optionOrDefault(options.numeric, "auto"),
+        style: optionOrDefault(options.style, "long"),
     }).format(amount, unit));
 }

package/dist/internal/freeTimeLedger.d.ts

@@ -13,6 +13,11 @@ export declare const MAX_WALKED_DAYS = 10000;
  * are counted against, `null` when every local day after expiry is charged.
  */
 export type FreeTimeTerms = {
+    /**
+     * The counting zone as the caller wrote it: a time zone identifier or a stored UTC offset
+     * (`±HH:MM[:SS]`), so always readable by `zoneFrame`. The walk's zoned values are placed with
+     * `frameZoned` and turned back with `frameInstant`.
+     */
     timeZone: string;
     firstDay: "eventDay" | "nextDay";
     calendar: ResolvedBusinessCalendar | null;

package/dist/internal/freeTimeLedger.js

@@ -1,8 +1,9 @@
 import { Temporal } from "@js-temporal/polyfill";
-import { isValidTimeZone } from "../zoned/validate/isValidTimeZone.js";
 import { isBusinessDate, parseBusinessCalendar, } from "./businessCalendar.js";
 import { isObject } from "./isObject.js";
 import { nextZonedBucketStart, zonedUnitStart } from "./zonedBucket.js";
+import { zoneFrame } from "./zoneFrame.js";
+import { certainlyTouchesMoreBuckets } from "./zoneBucketCap.js";
 /**
  * Local days a free-time walk may visit before giving up: the same cap as `bucketRange`. A
  * valid business calendar leaves at least one working day a week, so a working-day count needs
@@ -34,7 +35,7 @@ function readFreeTimeTerms(options, readChargeBasis = false) {
     if (firstDay !== "eventDay" && firstDay !== "nextDay") {
         return null;
     }
-    if (typeof timeZone !== "string" || !isValidTimeZone(timeZone)) {
+    if (typeof timeZone !== "string" || zoneFrame(timeZone) === null) {
         return null;
     }
     const needsCalendar = basis === "working" || (readChargeBasis && chargeBasis === "working");
@@ -209,6 +210,14 @@ export function walkFreeTime(clockStart, freeDays, terms, clockEnd) {
     let expiresAt = null;
     let expiryPending = false;
     let skipEventDay = terms.firstDay === "nextDay";
+    // A dwell that certainly touches more local days than the walk may visit ends it with the
+    // sentinel anyway: the walk needs one visit for every day the dwell touches, and one more to
+    // pass it. Deciding that from the span skips a 10,000-day walk. When it is not certain, the walk
+    // runs as before, so no answer changes.
+    if (clockEnd !== undefined &&
+        certainlyTouchesMoreBuckets(clockStart, clockEnd, "day", MAX_WALKED_DAYS)) {
+        return null;
+    }
     let day = localDayOf(clockStart);
     if (day === null) {
         return null;

package/dist/internal/index.d.ts

@@ -7,6 +7,7 @@ export { calendarOfAllDateValues, calendarSystemOfDateValue, } from "./calendarV
 export { calendarOfAllZonedValues, calendarSystemOfZonedValue, } from "./calendarValueOfZoned.js";
 export { formatZonedInCalendar, parseCalendarZonedValue, } from "./calendarZonedString.js";
 export { cycleFieldValue } from "./cycleFieldValue.js";
+export { isInDaylightTime, observesDaylightTime } from "./daylightTime.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";
@@ -14,13 +15,16 @@ export { isValidEpochNanoseconds, MAX_EPOCH_NANOSECOND_DIGITS, } from "./epochNa
 export { dateCycleFieldBounds } from "./dateCycleFieldBounds.js";
 export { timeCycleFieldBounds } from "./timeCycleFieldBounds.js";
 export { durationUntilString } from "./durationUntilString.js";
+export { EDIFACT_DTM_FORMATS, X12_DATE_TIME_PERIOD_FORMATS, X12_TIME_CODES, } from "./ediGrammar.js";
+export { exactDurationNanoseconds, nonNegativeExactDurationNanoseconds, } from "./exactDuration.js";
+export { type ExactMoment, readExactMoment, writeExactMoment, } from "./exactMoment.js";
 export { formatDateInCalendar } from "./formatDateInCalendar.js";
 export { bandsByTier, parseFreeDays, parseFreeTimeTerms, parseTiers, walkFreeTime, } from "./freeTimeLedger.js";
 export { halfOpenAbuts, halfOpenContainsPoint, halfOpenContainsSpan, halfOpenDifference, halfOpenIntersection, halfOpenMerge, halfOpenOverlap, halfOpenUnion, halfOpenXor, } from "./halfOpenIntervals.js";
-export { EXTENDED_UTC_OFFSET, isoStringBody, TIME_ZONE_ANNOTATION, } from "./isoStringBody.js";
+export { isoStringBody, TIME_ZONE_ANNOTATION } from "./isoStringBody.js";
 export { formatHourDuration } from "./hourDurationString.js";
 export { canonicalInstantIntervals } from "./instantIntervalText.js";
-export { parseInstantNanoseconds } from "./instantNanoseconds.js";
+export { instantFrom, parseInstantNanoseconds } from "./instantNanoseconds.js";
 export { coalesceIntervalNanoseconds, parseIntervalNanoseconds, parseIntervalNanosecondsList, } from "./intervalNanoseconds.js";
 export { resolveDurationRelativeTo } from "./resolveDurationRelativeTo.js";
 export { formatUtcOffset, parseUtcOffsetNanoseconds } from "./utcOffsetString.js";
@@ -39,17 +43,21 @@ 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 { parsePunctualityTolerance, punctualityOf } from "./punctuality.js";
 export { plainDateUntil } from "./plainDateUntil.js";
 export { resolveDateTimeUnit } from "./resolveDateTimeUnit.js";
+export { readDurationUnits } from "./readDurationUnits.js";
+export { DATE_FIELDS, DATE_TIME_FIELDS, readSetFields, TIME_FIELDS, } from "./readSetFields.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 { parseTimestampEvents } from "./timestampEvents.js";
 export { countZonedBuckets, nextZonedBucketStart, type WeekStartDay, zonedUnitEnd, zonedUnitStart, } from "./zonedBucket.js";
 export { countZonedLocalDates } from "./zonedLocalDates.js";
-export { utcOffsetStringNanoseconds, zonedDateTimeFrom, } from "./zonedWallClock.js";
+export { zonedDateTimeFrom } from "./zonedWallClock.js";
 export { wallClockAtOffset } from "./wallClockAtOffset.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";
+export { frameInstant, frameOffset, frameWallClock, frameZoned, instantOfWallClock, normalizeZoneFrame, zoneFrame, } from "./zoneFrame.js";

package/dist/internal/index.js

@@ -7,6 +7,7 @@ export { calendarOfAllDateValues, calendarSystemOfDateValue, } from "./calendarV
 export { calendarOfAllZonedValues, calendarSystemOfZonedValue, } from "./calendarValueOfZoned.js";
 export { formatZonedInCalendar, parseCalendarZonedValue, } from "./calendarZonedString.js";
 export { cycleFieldValue } from "./cycleFieldValue.js";
+export { isInDaylightTime, observesDaylightTime } from "./daylightTime.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";
@@ -14,13 +15,20 @@ export { isValidEpochNanoseconds, MAX_EPOCH_NANOSECOND_DIGITS, } from "./epochNa
 export { dateCycleFieldBounds } from "./dateCycleFieldBounds.js";
 export { timeCycleFieldBounds } from "./timeCycleFieldBounds.js";
 export { durationUntilString } from "./durationUntilString.js";
+// The EDI readers (./ediDateTimeFields) and writers (./ediDateTimeWriter) are deliberately not
+// re-exported here: they import `instant/convert/toOffsetInstant`, which reads this barrel at
+// module top level, so a barrel entry would close a cycle. Import each from its own file
+// ("../../internal/ediDateTimeFields", "../../internal/ediDateTimeWriter").
+export { EDIFACT_DTM_FORMATS, X12_DATE_TIME_PERIOD_FORMATS, X12_TIME_CODES, } from "./ediGrammar.js";
+export { exactDurationNanoseconds, nonNegativeExactDurationNanoseconds, } from "./exactDuration.js";
+export { readExactMoment, writeExactMoment, } from "./exactMoment.js";
 export { formatDateInCalendar } from "./formatDateInCalendar.js";
 export { bandsByTier, parseFreeDays, parseFreeTimeTerms, parseTiers, walkFreeTime, } from "./freeTimeLedger.js";
 export { halfOpenAbuts, halfOpenContainsPoint, halfOpenContainsSpan, halfOpenDifference, halfOpenIntersection, halfOpenMerge, halfOpenOverlap, halfOpenUnion, halfOpenXor, } from "./halfOpenIntervals.js";
-export { EXTENDED_UTC_OFFSET, isoStringBody, TIME_ZONE_ANNOTATION, } from "./isoStringBody.js";
+export { isoStringBody, TIME_ZONE_ANNOTATION } from "./isoStringBody.js";
 export { formatHourDuration } from "./hourDurationString.js";
 export { canonicalInstantIntervals } from "./instantIntervalText.js";
-export { parseInstantNanoseconds } from "./instantNanoseconds.js";
+export { instantFrom, parseInstantNanoseconds } from "./instantNanoseconds.js";
 export { coalesceIntervalNanoseconds, parseIntervalNanoseconds, parseIntervalNanosecondsList, } from "./intervalNanoseconds.js";
 export { resolveDurationRelativeTo } from "./resolveDurationRelativeTo.js";
 export { formatUtcOffset, parseUtcOffsetNanoseconds } from "./utcOffsetString.js";
@@ -39,17 +47,21 @@ 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 { parsePunctualityTolerance, punctualityOf } from "./punctuality.js";
 export { plainDateUntil } from "./plainDateUntil.js";
 export { resolveDateTimeUnit } from "./resolveDateTimeUnit.js";
+export { readDurationUnits } from "./readDurationUnits.js";
+export { DATE_FIELDS, DATE_TIME_FIELDS, readSetFields, TIME_FIELDS, } from "./readSetFields.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 { parseTimestampEvents } from "./timestampEvents.js";
 export { countZonedBuckets, nextZonedBucketStart, zonedUnitEnd, zonedUnitStart, } from "./zonedBucket.js";
 export { countZonedLocalDates } from "./zonedLocalDates.js";
-export { utcOffsetStringNanoseconds, zonedDateTimeFrom, } from "./zonedWallClock.js";
+export { zonedDateTimeFrom } from "./zonedWallClock.js";
 export { wallClockAtOffset } from "./wallClockAtOffset.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";
+export { frameInstant, frameOffset, frameWallClock, frameZoned, instantOfWallClock, normalizeZoneFrame, zoneFrame, } from "./zoneFrame.js";

package/dist/internal/instantFormatOptions.js

@@ -4,6 +4,7 @@
 // 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";
+import { optionOrDefault } from "./optionOrDefault.js";
 // GetDateTimeFormat requiredOptions for ~any~. `era` and `timeZoneName` are
 // deliberately absent: neither suppresses the defaults.
 const REQUIRED_FIELDS = [
@@ -58,7 +59,7 @@ export function instantFormatOptions(options, timeZone, defaults) {
         ...DEFAULT_FIELDS,
         ...(defaults === "zoned-date-time"
             ? {
-                timeZoneName: options.timeZoneName === undefined ? "short" : options.timeZoneName,
+                timeZoneName: optionOrDefault(options.timeZoneName, "short"),
             }
             : {}),
         timeZone,

package/dist/internal/instantNanoseconds.d.ts

@@ -1,16 +1,62 @@
+import { Temporal } from "@js-temporal/polyfill";
 /**
  * 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
+ * The single definition of "an instant string GMT accepts", and of the instant it names. Every
+ * GMT function that reads a moment without keeping its zone reads through here.
+ *
+ * **Which strings.** 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.
+ * (`[foo=bar]`) annotation never makes a string invalid, and an unknown critical one
+ * (`[!foo=bar]`) is rejected.
+ *
+ * **Which instant.** The written offset fixes it, as in `Temporal.Instant.from`, with one
+ * exception:
+ *
+ * - **A minute-rounded offset is read as its zone's real offset.** When the string has a
+ *   bracketed zone and an offset written to the minute, and that offset is the zone's actual
+ *   offset at that wall time rounded to the minute, the instant is the one the zone gives. This
+ *   is TC39 `ToTemporalZonedDateTime`'s match-minutes rule (`InterpretISODateTimeOffset`),
+ *   applied to the zone and the offset alone. It exists because
+ *   `Temporal.ZonedDateTime.prototype.toString` writes the offset rounded to the minute: in a
+ *   zone with a sub-minute offset (`Africa/Monrovia` before 1972, at −00:44:30, written
+ *   `-00:45`), the string a zoned function writes would otherwise be read up to 30 seconds off.
+ * - **The instant range is the only range.** The match has no `CheckISODaysRange` on the local
+ *   date, which `Temporal.ZonedDateTime.from` has, and does not need the written offset's own
+ *   reading to be in range. So every string Temporal writes for an instant in range is read
+ *   back, the first and last instants included: `-271821-04-19T23:58:45-00:01[Europe/London]`
+ *   (London's local mean time, −00:01:15) is the first instant, although its local date is
+ *   outside Temporal's date range and its reading at −00:01 is 15 seconds before the range.
+ * - **A repeated wall time inside a sub-minute offset change reads as its first pass.** The
+ *   match is against each candidate instant in order, so when a wall time happened twice and
+ *   the rounded offset fits the first pass, the first pass is the answer, even if the string
+ *   was written for the second. This is a class of strings, not one zone: it arises wherever a
+ *   zone's history has a fall-back of under a minute at a sub-minute offset. The example
+ *   test262 uses: Pacific/Niue moved from −11:19:40 to −11:20:00 at the end of
+ *   15 October 1952, so 23:59:40 to 23:59:59 happened twice, 20 seconds apart, and both passes
+ *   are written `-11:20`: `1952-10-15T23:59:59-11:20[Pacific/Niue]` reads as the pass at
+ *   −11:19:40. This is `Temporal.ZonedDateTime.from`'s own reading (test262
+ *   `intl402/Temporal/ZonedDateTime/from/zoneddatetime-sub-minute-offset.js`), and the one kind
+ *   of string Temporal writes that an instant reader does not read as the instant it was
+ *   written for. The exact offset, `-11:20:00`, names the second pass.
+ * - **Everything else keeps the written offset.** The complete list: a string without a
+ *   bracket; a `Z` instant; an offset written with seconds, which TC39 matches exactly
+ *   (`-00:45:00[Africa/Monrovia]` is −00:45:00); a bracket whose zone does not exist; and a
+ *   bracket whose zone has no instant in range with that wall time at the written offset or at
+ *   an offset that rounds to it (`-00:44[Africa/Monrovia]`, `-05:00[America/New_York]` in
+ *   June). Such a bracket is not validated here; a function that keeps the zone
+ *   (`transitTime`, `toOffsetInstant`) rejects it instead. Calendar and elective annotations
+ *   never change the reading. A string whose written reading is outside the instant range, and
+ *   which the zone does not bring inside it, is `null`.
+ *
+ * The zone's offset comes from Temporal's time-zone data; nothing here holds an offset or a
+ * zone name. A string in a whole-minute zone costs two offset lookups more than
+ * `Temporal.Instant.from`. 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
@@ -21,5 +67,25 @@
  * @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
+ * @example parseInstantNanoseconds("1960-01-01T00:20:00-00:45[Africa/Monrovia]") // -315615330000000000n — 01:04:30Z: Monrovia stood at -00:44:30
+ * @example parseInstantNanoseconds("1960-01-01T00:20:00-00:45") // -315615300000000000n — 01:05:00Z: no zone, so the offset is exact
+ * @example parseInstantNanoseconds("1952-10-15T23:59:59-11:20[Pacific/Niue]") // -543069621000000000n — the first pass of a repeated second, at -11:19:40
+ * @example parseInstantNanoseconds("-271821-04-19T23:58:45-00:01[Europe/London]") // -8640000000000000000000n — the first instant, at London's -00:01:15
+ * @example parseInstantNanoseconds("2024-06-15T10:00:00Z[Not/AZone]") // 1718445600000000000n — the bracket is not validated
  */
 export declare function parseInstantNanoseconds(value: string): bigint | null;
+/**
+ * `parseInstantNanoseconds` as a `Temporal.Instant`, for callers that already hold a validated
+ * string and go on to Temporal arithmetic. Use it wherever a caller's instant string would
+ * otherwise go to `Temporal.Instant.from`, so a minute-rounded offset is read the same way
+ * everywhere. Throws where `Temporal.Instant.from` throws, so it sits inside the caller's `try`
+ * like any other Temporal parse.
+ *
+ * @param value ISO 8601 instant or zoned datetime string
+ * @returns the instant the string names
+ * @throws RangeError when `value` is not a valid instant
+ *
+ * @example instantFrom("1960-01-01T00:20:00-00:45[Africa/Monrovia]").toString() // "1960-01-01T01:04:30Z"
+ * @example instantFrom("2024-06-15T10:00:00") // throws RangeError
+ */
+export declare function instantFrom(value: string): Temporal.Instant;