@northguild/gmt 1.16.0 → 1.18.0

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

@@ -0,0 +1,93 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { type ResolvedBusinessCalendar } from "./businessCalendar.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
+ * at most about seven local days per free or chargeable day. A walk that runs out answers with
+ * the sentinel, never a partial ledger.
+ */
+export declare const MAX_WALKED_DAYS = 10000;
+/**
+ * The tariff terms reduced to what the walk reads. `calendar` is the working-day calendar free
+ * days are counted against, `null` on the calendar basis; `chargeCalendar` is the one charged days
+ * are counted against, `null` when every local day after expiry is charged.
+ */
+export type FreeTimeTerms = {
+    timeZone: string;
+    firstDay: "eventDay" | "nextDay";
+    calendar: ResolvedBusinessCalendar | null;
+    chargeCalendar: ResolvedBusinessCalendar | null;
+};
+/**
+ * Read a `FreeTimeOptions` bag, or `null` when it is not one: a non-object, an unknown `basis`
+ * or `firstDay`, a missing `firstDay` (no default: the two conventions differ by a day of
+ * charges), an invalid `timeZone`, or a `"working"` basis without a valid `BusinessCalendar`.
+ * The `calendar` is read only when a basis that needs it is `"working"`.
+ *
+ * With `readChargeBasis`, `chargeBasis` is required too, and has no default for the same reason:
+ * where free time is in working days, tariffs mostly charge every calendar day after it, but some
+ * tariffs charge working days only, and the two differ by every closed day after expiry.
+ */
+export declare function parseFreeTimeTerms(options: unknown, readChargeBasis?: boolean): FreeTimeTerms | null;
+/** A whole number of free days no smaller than `minimum`, or `null`. */
+export declare function parseFreeDays(freeDays: unknown, minimum: 0 | 1): number | null;
+/**
+ * Read a `tiers` option: omitted means no bands, otherwise a strictly ascending list of positive
+ * safe whole chargeable-day ordinals, each the last day of its band, with no holes. Anything
+ * else is `null`.
+ */
+export declare function parseTiers(tiers: unknown): number[] | null;
+/**
+ * Split `chargeable` days into the bands `tiers` describes: `[5, 10]` is days 1–5, 6–10 and 11
+ * onward. Every band is listed, an empty one with `days: 0`, so a caller's rate table lines up
+ * by index; the last band is always open (`to: null`).
+ */
+export declare function bandsByTier(tiers: number[], chargeable: number): {
+    from: number;
+    to: number | null;
+    days: number;
+}[];
+/** One local date of the terminal: its first instant, and its ISO label. */
+export interface LedgerDay {
+    start: Temporal.ZonedDateTime;
+    date: string;
+    /**
+     * True when the date began before the first instant Temporal represents, so `start` is the
+     * clock start standing in for it. Such a start is never output: it can only anchor the walk.
+     */
+    clamped?: boolean;
+}
+/** What `walkFreeTime` returns: the free days, the expiry, and what the dwell used and owes. */
+export interface FreeTimeLedger {
+    /** The free days in order, exactly `freeDays` of them. */
+    free: LedgerDay[];
+    /** The first instant of the local day after the last free day; with no free days, of day one. */
+    expiresAt: Temporal.ZonedDateTime;
+    /** Free days the half-open dwell `[clockStart, clockEnd)` touched; `0` with no `clockEnd`. */
+    used: number;
+    /** Counted days from `expiresAt` that the dwell touched, in order; empty with no `clockEnd`. */
+    charged: LedgerDay[];
+}
+/**
+ * Walk the terminal's real local days from the clock start and lay out free time and charges.
+ *
+ * Each day is a bucket `zonedUnitStart` / `nextZonedBucketStart` returns for `"day"`, the same
+ * boundaries `floorToZone` and `bucketRange` use, so a 23- or 25-hour day is one day, a date the
+ * zone deleted is never visited, and a date the clock falls back into is one day. Free days and
+ * charged days are counted against their own terms: on a working basis a weekend day or holiday is
+ * visited but not counted; on a calendar basis every day counts. The day of the event is neither
+ * free nor charged under `"nextDay"`.
+ *
+ * - Free days are the first `freeDays` days counted on `calendar`. `expiresAt` is the start of the
+ *   day after the last of them, whether or not that day counts; with `freeDays` of `0` it is the
+ *   start of the first counted day.
+ * - With a `clockEnd`, the dwell `[clockStart, clockEnd)` is half-open: a day is touched when it
+ *   starts before `clockEnd`, and a zero-length dwell touches the day it sits on, as `dwellTime`
+ *   counts. `used` is the free days touched; `charged` the days from `expiresAt` touched that count
+ *   on `chargeCalendar`.
+ * - An event day that began before the first representable instant is still walked from the
+ *   clock start; only an expiry that would be that unrepresentable start is refused.
+ * - Returns `null` when the walk would visit more than `MAX_WALKED_DAYS` local days, when a day
+ *   boundary cannot be found, or when the expiry lies outside the representable range.
+ */
+export declare function walkFreeTime(clockStart: Temporal.ZonedDateTime, freeDays: number, terms: FreeTimeTerms, clockEnd?: Temporal.ZonedDateTime): FreeTimeLedger | null;

package/dist/internal/freeTimeLedger.js

@@ -0,0 +1,262 @@
+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";
+/**
+ * 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
+ * at most about seven local days per free or chargeable day. A walk that runs out answers with
+ * the sentinel, never a partial ledger.
+ */
+export const MAX_WALKED_DAYS = 10_000;
+/**
+ * Buckets stepped over while looking for a later date. A fall-back that re-enters the previous
+ * date (`America/Goose_Bay`, 2010-11-07 00:01 back into the 6th) opens a one-minute 7 November
+ * bucket, then a 6 November one, then 7 November again: two buckets in a row whose date is not
+ * later than the day being left. One transition can do no more than that, so eight is a
+ * generous bound.
+ */
+const MAX_REVISITED_BUCKETS = 8;
+/** `parseFreeTimeTerms` without the guard; every read of `options` happens here. */
+function readFreeTimeTerms(options, readChargeBasis = false) {
+    if (!isObject(options)) {
+        return null;
+    }
+    const { basis, chargeBasis, firstDay, timeZone, calendar } = options;
+    const isBasis = (value) => value === "calendar" || value === "working";
+    if (!isBasis(basis)) {
+        return null;
+    }
+    if (readChargeBasis && !isBasis(chargeBasis)) {
+        return null;
+    }
+    if (firstDay !== "eventDay" && firstDay !== "nextDay") {
+        return null;
+    }
+    if (typeof timeZone !== "string" || !isValidTimeZone(timeZone)) {
+        return null;
+    }
+    const needsCalendar = basis === "working" || (readChargeBasis && chargeBasis === "working");
+    const resolved = needsCalendar ? parseBusinessCalendar(calendar) : null;
+    if (needsCalendar && resolved === null) {
+        return null;
+    }
+    return {
+        timeZone,
+        firstDay,
+        calendar: basis === "working" ? resolved : null,
+        chargeCalendar: readChargeBasis && chargeBasis === "working" ? resolved : null,
+    };
+}
+/**
+ * Read a `FreeTimeOptions` bag, or `null` when it is not one: a non-object, an unknown `basis`
+ * or `firstDay`, a missing `firstDay` (no default: the two conventions differ by a day of
+ * charges), an invalid `timeZone`, or a `"working"` basis without a valid `BusinessCalendar`.
+ * The `calendar` is read only when a basis that needs it is `"working"`.
+ *
+ * With `readChargeBasis`, `chargeBasis` is required too, and has no default for the same reason:
+ * where free time is in working days, tariffs mostly charge every calendar day after it, but some
+ * tariffs charge working days only, and the two differ by every closed day after expiry.
+ */
+export function parseFreeTimeTerms(options, readChargeBasis = false) {
+    try {
+        return readFreeTimeTerms(options, readChargeBasis);
+    }
+    catch {
+        // Never throws (Core Rule 3): a Proxy or getter that throws on access is invalid input.
+        return null;
+    }
+}
+/** A whole number of free days no smaller than `minimum`, or `null`. */
+export function parseFreeDays(freeDays, minimum) {
+    return typeof freeDays === "number" &&
+        Number.isSafeInteger(freeDays) &&
+        freeDays >= minimum
+        ? freeDays
+        : null;
+}
+/**
+ * Read a `tiers` option: omitted means no bands, otherwise a strictly ascending list of positive
+ * safe whole chargeable-day ordinals, each the last day of its band, with no holes. Anything
+ * else is `null`.
+ */
+export function parseTiers(tiers) {
+    if (tiers === undefined) {
+        return [];
+    }
+    if (!Array.isArray(tiers)) {
+        return null;
+    }
+    // `Array.from` fills holes with `undefined`, which the check below rejects; `every` alone
+    // would skip them and let `[5, , ]` through to a `NaN` band.
+    const items = Array.from(tiers);
+    const ascending = items.every((tier, index) => typeof tier === "number" &&
+        Number.isSafeInteger(tier) &&
+        tier >= 1 &&
+        (index === 0 || tier > items[index - 1]));
+    return ascending ? items : null;
+}
+/**
+ * Split `chargeable` days into the bands `tiers` describes: `[5, 10]` is days 1–5, 6–10 and 11
+ * onward. Every band is listed, an empty one with `days: 0`, so a caller's rate table lines up
+ * by index; the last band is always open (`to: null`).
+ */
+export function bandsByTier(tiers, chargeable) {
+    const bands = [];
+    let from = 1;
+    for (const to of tiers) {
+        bands.push({
+            from,
+            to,
+            days: Math.max(0, Math.min(chargeable, to) - from + 1),
+        });
+        from = to + 1;
+    }
+    bands.push({ from, to: null, days: Math.max(0, chargeable - from + 1) });
+    return bands;
+}
+/** The local day holding `zoned`, or `null` when its start cannot be found. */
+function localDayOf(zoned) {
+    let start;
+    try {
+        start = zonedUnitStart(zoned, "day");
+    }
+    catch (error) {
+        if (!(error instanceof RangeError))
+            throw error;
+        // The event day began before Temporal's first instant (-271821-04-20T00:00Z in a zone west
+        // of UTC). Its date is still known, and every later day boundary is representable, so the
+        // clock start anchors the walk in its place.
+        return {
+            start: zoned,
+            date: zoned.toPlainDate().toString(),
+            clamped: true,
+        };
+    }
+    return start === null
+        ? null
+        : { start, date: start.toPlainDate().toString() };
+}
+/**
+ * The first local day after `day` whose date is later than `day`'s. A bucket that re-enters an
+ * earlier or equal date is folded into the day already laid out: a clock that starts in the
+ * one-minute first pass of Goose Bay's 7 November must not free or charge the 6th, and
+ * `countZonedLocalDates` counts a re-entered date once. `undefined` when the next day starts
+ * past the last representable instant, `null` when the walk gives up.
+ */
+function nextLocalDay(day) {
+    const current = day.start.toPlainDate();
+    let cursor = day.start;
+    for (let i = 0; i < MAX_REVISITED_BUCKETS; i++) {
+        let next;
+        try {
+            next = nextZonedBucketStart(cursor, "day");
+        }
+        catch (error) {
+            if (error instanceof RangeError)
+                return undefined;
+            throw error;
+        }
+        if (next === null) {
+            return null;
+        }
+        const date = next.toPlainDate();
+        if (Temporal.PlainDate.compare(date, current) > 0) {
+            return { start: next, date: date.toString() };
+        }
+        cursor = next;
+    }
+    return null;
+}
+/**
+ * Walk the terminal's real local days from the clock start and lay out free time and charges.
+ *
+ * Each day is a bucket `zonedUnitStart` / `nextZonedBucketStart` returns for `"day"`, the same
+ * boundaries `floorToZone` and `bucketRange` use, so a 23- or 25-hour day is one day, a date the
+ * zone deleted is never visited, and a date the clock falls back into is one day. Free days and
+ * charged days are counted against their own terms: on a working basis a weekend day or holiday is
+ * visited but not counted; on a calendar basis every day counts. The day of the event is neither
+ * free nor charged under `"nextDay"`.
+ *
+ * - Free days are the first `freeDays` days counted on `calendar`. `expiresAt` is the start of the
+ *   day after the last of them, whether or not that day counts; with `freeDays` of `0` it is the
+ *   start of the first counted day.
+ * - With a `clockEnd`, the dwell `[clockStart, clockEnd)` is half-open: a day is touched when it
+ *   starts before `clockEnd`, and a zero-length dwell touches the day it sits on, as `dwellTime`
+ *   counts. `used` is the free days touched; `charged` the days from `expiresAt` touched that count
+ *   on `chargeCalendar`.
+ * - An event day that began before the first representable instant is still walked from the
+ *   clock start; only an expiry that would be that unrepresentable start is refused.
+ * - Returns `null` when the walk would visit more than `MAX_WALKED_DAYS` local days, when a day
+ *   boundary cannot be found, or when the expiry lies outside the representable range.
+ */
+export function walkFreeTime(clockStart, freeDays, terms, clockEnd) {
+    // The dwell's last instant, one nanosecond before the exit; a zero-length dwell is its own point.
+    const last = clockEnd === undefined
+        ? undefined
+        : Temporal.ZonedDateTime.compare(clockStart, clockEnd) < 0
+            ? clockEnd.subtract({ nanoseconds: 1 })
+            : clockEnd;
+    const touched = (day) => last !== undefined && Temporal.ZonedDateTime.compare(day.start, last) <= 0;
+    const counts = (day) => terms.calendar === null ||
+        isBusinessDate(day.start.toPlainDate(), terms.calendar);
+    const charges = (day) => terms.chargeCalendar === null ||
+        isBusinessDate(day.start.toPlainDate(), terms.chargeCalendar);
+    const free = [];
+    const charged = [];
+    let used = 0;
+    let expiresAt = null;
+    let expiryPending = false;
+    let skipEventDay = terms.firstDay === "nextDay";
+    let day = localDayOf(clockStart);
+    if (day === null) {
+        return null;
+    }
+    // One more visit than the cap: the day after the last touched one is what ends the walk.
+    for (let i = 0; i <= MAX_WALKED_DAYS; i++) {
+        const eventDaySkipped = skipEventDay;
+        const counted = !skipEventDay && counts(day);
+        skipEventDay = false;
+        if (expiryPending) {
+            expiresAt = day.start;
+            expiryPending = false;
+        }
+        else if (expiresAt === null && counted) {
+            if (freeDays === 0) {
+                // With no free time the expiry is day one's start, which must be a real instant.
+                if (day.clamped)
+                    return null;
+                expiresAt = day.start;
+            }
+            else {
+                free.push(day);
+                if (touched(day))
+                    used++;
+                expiryPending = free.length === freeDays;
+            }
+        }
+        if (expiresAt !== null) {
+            // Free time has ended; with no clock end there is nothing more to lay out.
+            if (last === undefined) {
+                return { free, expiresAt, used, charged };
+            }
+            if (Temporal.ZonedDateTime.compare(day.start, last) > 0) {
+                return { free, expiresAt, used, charged };
+            }
+            // The day of the event under `nextDay` is never charged: free time has not started on it.
+            if (!eventDaySkipped && charges(day))
+                charged.push(day);
+        }
+        const next = nextLocalDay(day);
+        if (next === undefined) {
+            // No representable day follows: free time can still be laid out only if it has ended.
+            return expiresAt === null ? null : { free, expiresAt, used, charged };
+        }
+        if (next === null) {
+            return null;
+        }
+        day = next;
+    }
+    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,12 +15,15 @@ export { isValidEpochNanoseconds, MAX_EPOCH_NANOSECOND_DIGITS, } from "./epochNa
 export { dateCycleFieldBounds } from "./dateCycleFieldBounds.js";
 export { timeCycleFieldBounds } from "./timeCycleFieldBounds.js";
 export { durationUntilString } from "./durationUntilString.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 { isoStringBody } 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";
@@ -38,6 +42,7 @@ 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 { resolveDurationUnit } from "./resolveDurationUnit.js";
@@ -45,9 +50,11 @@ 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 { 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 { addToZoned, addToZonedDisambiguated, plainToZoned, roundZonedDateTime, subtractFromZoned, withZonedFields, zonedHoursInDay, zonedNextTransition, zonedPreviousTransition, zonedStartOfDay, } from "./zonedWallClockOperations.js";
 export { zonelessCalendarDate } from "./zonelessCalendarDate.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,12 +15,15 @@ export { isValidEpochNanoseconds, MAX_EPOCH_NANOSECOND_DIGITS, } from "./epochNa
 export { dateCycleFieldBounds } from "./dateCycleFieldBounds.js";
 export { timeCycleFieldBounds } from "./timeCycleFieldBounds.js";
 export { durationUntilString } from "./durationUntilString.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 { isoStringBody } 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";
@@ -38,6 +42,7 @@ 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 { resolveDurationUnit } from "./resolveDurationUnit.js";
@@ -45,9 +50,11 @@ 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 { 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 { addToZoned, addToZonedDisambiguated, plainToZoned, roundZonedDateTime, subtractFromZoned, withZonedFields, zonedHoursInDay, zonedNextTransition, zonedPreviousTransition, zonedStartOfDay, } from "./zonedWallClockOperations.js";
 export { zonelessCalendarDate } from "./zonelessCalendarDate.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;