@northguild/gmt 1.15.0 → 1.16.0

package/dist/internal/foreignEpochs.d.ts

@@ -0,0 +1,134 @@
+/**
+ * The magic numbers behind `precision/convert/`'s foreign-epoch bridges, in one place.
+ *
+ * Every integration that talks to NTP, Windows, .NET, Excel or PostgreSQL re-derives these
+ * constants, usually wrongly. They live here so each `to*`/`from*` pair reads from the same
+ * declaration and `foreignEpochs.test.ts` can assert every one of them against a real
+ * `Temporal` day count rather than against the arithmetic that consumes them.
+ *
+ * | Format | Epoch | Unit | Representable range |
+ * | --- | --- | --- | --- |
+ * | NTP | 1900-01-01 | 2^-32 s | 64 bits, wrapping every 2^32 s (~136.19 years) into a new era |
+ * | FILETIME | 1601-01-01 | 100 ns | `0n` to 2^63 − 1, 1601-01-01 to +030828-09-14 (`FileTimeToSystemTime`'s limit) |
+ * | .NET ticks | 0001-01-01 | 100 ns | `DateTime.MinValue` to `DateTime.MaxValue`, 0001-01-01 to 9999-12-31 |
+ * | Excel 1900 | 1899-12-30 | 1 day | serial 1 (1900-01-01) to 2958465 (9999-12-31); 60 is the phantom 1900-02-29 |
+ * | Excel 1904 | 1904-01-01 | 1 day | serial 0 (1904-01-01) to 2957003 (9999-12-31) |
+ * | PostgreSQL | 2000-01-01 | 1 µs | `MIN_TIMESTAMP` (4713 BC) up; capped above by `Temporal.Instant`, not by int64 |
+ *
+ * Sources: [FILETIME epoch](https://devblogs.microsoft.com/oldnewthing/20090306-00/?p=18913),
+ * [NTP eras](https://www.eecis.udel.edu/~mills/y2k.html),
+ * [.NET ticks](https://www.epochconverter.com/dotnet).
+ */
+/** Nanoseconds in one second. */
+export declare const NANOSECONDS_PER_SECOND = 1000000000n;
+/** Nanoseconds in one millisecond — the finest grid an Excel serial's `double` can carry. */
+export declare const NANOSECONDS_PER_MILLISECOND = 1000000n;
+/** Nanoseconds in one microsecond — PostgreSQL `timestamptz` resolution. */
+export declare const NANOSECONDS_PER_MICROSECOND = 1000n;
+/** Nanoseconds in one 100-nanosecond tick — the unit FILETIME and .NET ticks share. */
+export declare const NANOSECONDS_PER_TICK = 100n;
+/** Nanoseconds in one 24-hour day. */
+export declare const NANOSECONDS_PER_DAY = 86400000000000n;
+/** The same value as a `number` — an Excel serial is days in a `double`. */
+export declare const NANOSECONDS_PER_DAY_NUMBER = 86400000000000;
+/** Milliseconds in one 24-hour day. Excel serials round to this grid; see `fromExcelSerial`. */
+export declare const MILLISECONDS_PER_DAY = 86400000;
+/**
+ * Fractional units in one NTP second: the low 32 bits of the timestamp count 2^-32 s,
+ * i.e. ~232.83 picoseconds.
+ */
+export declare const NTP_UNITS_PER_SECOND = 4294967296n;
+/**
+ * Values in one NTP era: 2^64, the whole 64-bit timestamp. The seconds field is unsigned
+ * 32-bit, so the timestamp wraps here — every 2^32 seconds, or ~136.19 years.
+ */
+export declare const NTP_ERA_UNITS = 18446744073709551616n;
+/**
+ * Nanoseconds from 1900-01-01 (the NTP epoch) to 1970-01-01: 2 208 988 800 s, the delta
+ * RFC 5905 names for converting an NTP timestamp to a Unix one.
+ */
+export declare const NTP_EPOCH_OFFSET_NANOSECONDS = 2208988800000000000n;
+/**
+ * 100-nanosecond intervals from 1601-01-01 (the FILETIME epoch) to 1970-01-01:
+ * 11 644 473 600 s, the constant every Win32-to-Unix conversion carries.
+ */
+export declare const FILE_TIME_EPOCH_OFFSET_TICKS = 116444736000000000n;
+/** Smallest FILETIME: `FILETIME` is a pair of `DWORD`s, so the value is unsigned. */
+export declare const MIN_FILE_TIME = 0n;
+/**
+ * Largest convertible FILETIME: 2^63 − 1, i.e. `+030828-09-14T02:48:05.4775807Z`.
+ *
+ * The struct's two `DWORD`s hold up to 2^64 − 1, but Microsoft's `FileTimeToSystemTime`
+ * says the value "must be less than 0x8000000000000000. Otherwise, the function fails", and
+ * `SetFileTime` reserves `0xFFFFFFFF`/`0xFFFFFFFF` (2^64 − 1) as a "do not modify" marker
+ * rather than a time. Values from 2^63 up are therefore not dates.
+ * Source: https://learn.microsoft.com/en-us/windows/win32/api/timezoneapi/nf-timezoneapi-filetimetosystemtime
+ */
+export declare const MAX_FILE_TIME = 9223372036854775807n;
+/**
+ * 100-nanosecond intervals from 0001-01-01 (the `DateTime` epoch, proleptic Gregorian) to
+ * 1970-01-01. `DateTime.UnixEpoch.Ticks` in .NET.
+ */
+export declare const DOT_NET_TICKS_EPOCH_OFFSET = 621355968000000000n;
+/** `DateTime.MinValue.Ticks` — 0001-01-01T00:00:00. */
+export declare const MIN_DOT_NET_TICKS = 0n;
+/** `DateTime.MaxValue.Ticks` — 9999-12-31T23:59:59.9999999. */
+export declare const MAX_DOT_NET_TICKS = 3155378975999999999n;
+/**
+ * Nanoseconds at 1899-12-30, serial 0 of the 1900 date system.
+ *
+ * Serial 0 is *not* 1899-12-31, even though serial 1 is 1900-01-01: the system counts the
+ * phantom 29 February 1900 that Lotus 1-2-3 invented and Excel keeps for compatibility, so
+ * everything from serial 61 on sits one day later than a naive count would put it. Serials
+ * 1–59 are offset from `EXCEL_1900_PRE_PHANTOM_EPOCH_NANOSECONDS` instead.
+ */
+export declare const EXCEL_1900_EPOCH_NANOSECONDS = -2209161600000000000n;
+/**
+ * Nanoseconds at 1899-12-31 — the effective serial 0 for the 1900 system's serials 1–59,
+ * which precede the phantom leap day.
+ */
+export declare const EXCEL_1900_PRE_PHANTOM_EPOCH_NANOSECONDS = -2209075200000000000n;
+/** Nanoseconds at 1904-01-01, serial 0 of the legacy Mac 1904 date system. */
+export declare const EXCEL_1904_EPOCH_NANOSECONDS = -2082844800000000000n;
+/**
+ * Days between the two systems' serial 0. A 1900-system serial is exactly 1462 higher than
+ * the 1904-system serial for the same date (once past the phantom day).
+ */
+export declare const EXCEL_SYSTEM_DAY_DELTA = 1462;
+/** Excel's first real 1900-system serial: 1 is 1900-01-01. Serial 0 renders as "January 0". */
+export declare const MIN_EXCEL_1900_SERIAL = 1;
+/** Excel's first 1904-system serial: 0 is 1904-01-01. */
+export declare const MIN_EXCEL_1904_SERIAL = 0;
+/**
+ * One past Excel's last 1900-system serial. 2958465 is 9999-12-31, so anything below
+ * 2958466 is inside 9999-12-31.
+ */
+export declare const MAX_EXCEL_1900_SERIAL_EXCLUSIVE = 2958466;
+/** One past Excel's last 1904-system serial. 2957003 is 9999-12-31. */
+export declare const MAX_EXCEL_1904_SERIAL_EXCLUSIVE = 2957004;
+/**
+ * The 1900 system's phantom serial: 60 is 29 February 1900, a date that never existed —
+ * 1900 was not a leap year. The whole serial day `[60, 61)` has no instant behind it.
+ */
+export declare const EXCEL_PHANTOM_SERIAL = 60;
+/**
+ * Nanoseconds at 1900-03-01, the first instant the 1900 system's serials stop needing the
+ * phantom-day correction.
+ */
+export declare const EXCEL_1900_PHANTOM_END_NANOSECONDS = -2203891200000000000n;
+/**
+ * Microseconds from 1970-01-01 to 2000-01-01, PostgreSQL's internal `timestamptz` epoch:
+ * 946 684 800 s.
+ */
+export declare const PG_EPOCH_OFFSET_MICROSECONDS = 946684800000000n;
+/**
+ * PostgreSQL's smallest `timestamp`/`timestamptz`: `MIN_TIMESTAMP` in
+ * `src/include/datatype/timestamp.h`, i.e. Julian Day 0 — `-004713-11-24T00:00:00Z` in the
+ * proleptic Gregorian calendar the ISO strings use, which is the 4713 BC the manual names in
+ * the *Julian* calendar.
+ *
+ * There is no matching maximum here: PostgreSQL's `END_TIMESTAMP` (9223371331200000000, one
+ * past 294276-12-31) is beyond what `Temporal.Instant` can represent, so the instant range
+ * binds first and a second constant would be unreachable.
+ */
+export declare const MIN_PG_MICROSECONDS = -211813488000000000n;

package/dist/internal/foreignEpochs.js

@@ -0,0 +1,139 @@
+/**
+ * The magic numbers behind `precision/convert/`'s foreign-epoch bridges, in one place.
+ *
+ * Every integration that talks to NTP, Windows, .NET, Excel or PostgreSQL re-derives these
+ * constants, usually wrongly. They live here so each `to*`/`from*` pair reads from the same
+ * declaration and `foreignEpochs.test.ts` can assert every one of them against a real
+ * `Temporal` day count rather than against the arithmetic that consumes them.
+ *
+ * | Format | Epoch | Unit | Representable range |
+ * | --- | --- | --- | --- |
+ * | NTP | 1900-01-01 | 2^-32 s | 64 bits, wrapping every 2^32 s (~136.19 years) into a new era |
+ * | FILETIME | 1601-01-01 | 100 ns | `0n` to 2^63 − 1, 1601-01-01 to +030828-09-14 (`FileTimeToSystemTime`'s limit) |
+ * | .NET ticks | 0001-01-01 | 100 ns | `DateTime.MinValue` to `DateTime.MaxValue`, 0001-01-01 to 9999-12-31 |
+ * | Excel 1900 | 1899-12-30 | 1 day | serial 1 (1900-01-01) to 2958465 (9999-12-31); 60 is the phantom 1900-02-29 |
+ * | Excel 1904 | 1904-01-01 | 1 day | serial 0 (1904-01-01) to 2957003 (9999-12-31) |
+ * | PostgreSQL | 2000-01-01 | 1 µs | `MIN_TIMESTAMP` (4713 BC) up; capped above by `Temporal.Instant`, not by int64 |
+ *
+ * Sources: [FILETIME epoch](https://devblogs.microsoft.com/oldnewthing/20090306-00/?p=18913),
+ * [NTP eras](https://www.eecis.udel.edu/~mills/y2k.html),
+ * [.NET ticks](https://www.epochconverter.com/dotnet).
+ */
+/** Nanoseconds in one second. */
+export const NANOSECONDS_PER_SECOND = 1000000000n;
+/** Nanoseconds in one millisecond — the finest grid an Excel serial's `double` can carry. */
+export const NANOSECONDS_PER_MILLISECOND = 1000000n;
+/** Nanoseconds in one microsecond — PostgreSQL `timestamptz` resolution. */
+export const NANOSECONDS_PER_MICROSECOND = 1000n;
+/** Nanoseconds in one 100-nanosecond tick — the unit FILETIME and .NET ticks share. */
+export const NANOSECONDS_PER_TICK = 100n;
+/** Nanoseconds in one 24-hour day. */
+export const NANOSECONDS_PER_DAY = 86400000000000n;
+/** The same value as a `number` — an Excel serial is days in a `double`. */
+export const NANOSECONDS_PER_DAY_NUMBER = 86_400_000_000_000;
+/** Milliseconds in one 24-hour day. Excel serials round to this grid; see `fromExcelSerial`. */
+export const MILLISECONDS_PER_DAY = 86_400_000;
+// --- NTP (RFC 5905) -------------------------------------------------------
+/**
+ * Fractional units in one NTP second: the low 32 bits of the timestamp count 2^-32 s,
+ * i.e. ~232.83 picoseconds.
+ */
+export const NTP_UNITS_PER_SECOND = 4294967296n;
+/**
+ * Values in one NTP era: 2^64, the whole 64-bit timestamp. The seconds field is unsigned
+ * 32-bit, so the timestamp wraps here — every 2^32 seconds, or ~136.19 years.
+ */
+export const NTP_ERA_UNITS = 18446744073709551616n;
+/**
+ * Nanoseconds from 1900-01-01 (the NTP epoch) to 1970-01-01: 2 208 988 800 s, the delta
+ * RFC 5905 names for converting an NTP timestamp to a Unix one.
+ */
+export const NTP_EPOCH_OFFSET_NANOSECONDS = 2208988800000000000n;
+// --- Windows FILETIME -----------------------------------------------------
+/**
+ * 100-nanosecond intervals from 1601-01-01 (the FILETIME epoch) to 1970-01-01:
+ * 11 644 473 600 s, the constant every Win32-to-Unix conversion carries.
+ */
+export const FILE_TIME_EPOCH_OFFSET_TICKS = 116444736000000000n;
+/** Smallest FILETIME: `FILETIME` is a pair of `DWORD`s, so the value is unsigned. */
+export const MIN_FILE_TIME = 0n;
+/**
+ * Largest convertible FILETIME: 2^63 − 1, i.e. `+030828-09-14T02:48:05.4775807Z`.
+ *
+ * The struct's two `DWORD`s hold up to 2^64 − 1, but Microsoft's `FileTimeToSystemTime`
+ * says the value "must be less than 0x8000000000000000. Otherwise, the function fails", and
+ * `SetFileTime` reserves `0xFFFFFFFF`/`0xFFFFFFFF` (2^64 − 1) as a "do not modify" marker
+ * rather than a time. Values from 2^63 up are therefore not dates.
+ * Source: https://learn.microsoft.com/en-us/windows/win32/api/timezoneapi/nf-timezoneapi-filetimetosystemtime
+ */
+export const MAX_FILE_TIME = 9223372036854775807n;
+// --- .NET ticks -----------------------------------------------------------
+/**
+ * 100-nanosecond intervals from 0001-01-01 (the `DateTime` epoch, proleptic Gregorian) to
+ * 1970-01-01. `DateTime.UnixEpoch.Ticks` in .NET.
+ */
+export const DOT_NET_TICKS_EPOCH_OFFSET = 621355968000000000n;
+/** `DateTime.MinValue.Ticks` — 0001-01-01T00:00:00. */
+export const MIN_DOT_NET_TICKS = 0n;
+/** `DateTime.MaxValue.Ticks` — 9999-12-31T23:59:59.9999999. */
+export const MAX_DOT_NET_TICKS = 3155378975999999999n;
+// --- Excel day serials ----------------------------------------------------
+/**
+ * Nanoseconds at 1899-12-30, serial 0 of the 1900 date system.
+ *
+ * Serial 0 is *not* 1899-12-31, even though serial 1 is 1900-01-01: the system counts the
+ * phantom 29 February 1900 that Lotus 1-2-3 invented and Excel keeps for compatibility, so
+ * everything from serial 61 on sits one day later than a naive count would put it. Serials
+ * 1–59 are offset from `EXCEL_1900_PRE_PHANTOM_EPOCH_NANOSECONDS` instead.
+ */
+export const EXCEL_1900_EPOCH_NANOSECONDS = -2209161600000000000n;
+/**
+ * Nanoseconds at 1899-12-31 — the effective serial 0 for the 1900 system's serials 1–59,
+ * which precede the phantom leap day.
+ */
+export const EXCEL_1900_PRE_PHANTOM_EPOCH_NANOSECONDS = -2209075200000000000n;
+/** Nanoseconds at 1904-01-01, serial 0 of the legacy Mac 1904 date system. */
+export const EXCEL_1904_EPOCH_NANOSECONDS = -2082844800000000000n;
+/**
+ * Days between the two systems' serial 0. A 1900-system serial is exactly 1462 higher than
+ * the 1904-system serial for the same date (once past the phantom day).
+ */
+export const EXCEL_SYSTEM_DAY_DELTA = 1462;
+/** Excel's first real 1900-system serial: 1 is 1900-01-01. Serial 0 renders as "January 0". */
+export const MIN_EXCEL_1900_SERIAL = 1;
+/** Excel's first 1904-system serial: 0 is 1904-01-01. */
+export const MIN_EXCEL_1904_SERIAL = 0;
+/**
+ * One past Excel's last 1900-system serial. 2958465 is 9999-12-31, so anything below
+ * 2958466 is inside 9999-12-31.
+ */
+export const MAX_EXCEL_1900_SERIAL_EXCLUSIVE = 2_958_466;
+/** One past Excel's last 1904-system serial. 2957003 is 9999-12-31. */
+export const MAX_EXCEL_1904_SERIAL_EXCLUSIVE = 2_957_004;
+/**
+ * The 1900 system's phantom serial: 60 is 29 February 1900, a date that never existed —
+ * 1900 was not a leap year. The whole serial day `[60, 61)` has no instant behind it.
+ */
+export const EXCEL_PHANTOM_SERIAL = 60;
+/**
+ * Nanoseconds at 1900-03-01, the first instant the 1900 system's serials stop needing the
+ * phantom-day correction.
+ */
+export const EXCEL_1900_PHANTOM_END_NANOSECONDS = -2203891200000000000n;
+// --- PostgreSQL -----------------------------------------------------------
+/**
+ * Microseconds from 1970-01-01 to 2000-01-01, PostgreSQL's internal `timestamptz` epoch:
+ * 946 684 800 s.
+ */
+export const PG_EPOCH_OFFSET_MICROSECONDS = 946684800000000n;
+/**
+ * PostgreSQL's smallest `timestamp`/`timestamptz`: `MIN_TIMESTAMP` in
+ * `src/include/datatype/timestamp.h`, i.e. Julian Day 0 — `-004713-11-24T00:00:00Z` in the
+ * proleptic Gregorian calendar the ISO strings use, which is the 4713 BC the manual names in
+ * the *Julian* calendar.
+ *
+ * There is no matching maximum here: PostgreSQL's `END_TIMESTAMP` (9223371331200000000, one
+ * past 294276-12-31) is beyond what `Temporal.Instant` can represent, so the instant range
+ * binds first and a second constant would be unreachable.
+ */
+export const MIN_PG_MICROSECONDS = -211813488000000000n;

package/dist/internal/formatCalendarDays.d.ts

@@ -0,0 +1,28 @@
+import type { Temporal } from "@js-temporal/polyfill";
+/**
+ * Render a calendar phrase for a moment `diffDays` calendar days from the reference: "tomorrow at
+ * 2:30 PM" within six days, else the long date and time. Shared by the zoned, utc and unix
+ * calendar formatters.
+ *
+ * @param diffDays signed calendar-day distance from the reference, in `timeZone`
+ * @param epochMilliseconds the moment to render
+ * @param timeZone IANA zone the clock time is rendered in
+ * @param locale BCP 47 locale(s) passed through to `Intl`
+ * @param timeStyle the `Intl.DateTimeFormat` time style
+ * @returns the phrase; throws where `Intl` throws, for the caller's sentinel
+ * @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;
+/**
+ * `formatCalendarDays` for two instants, counting calendar days between their dates in `timeZone`.
+ *
+ * @param target the moment to render
+ * @param reference the moment "today" is read from
+ * @param timeZone IANA zone both dates and the clock time are read in
+ * @param locale BCP 47 locale(s) passed through to `Intl`
+ * @param timeStyle the `Intl.DateTimeFormat` time style
+ * @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;

package/dist/internal/formatCalendarDays.js

@@ -0,0 +1,49 @@
+import { joinDateTimeConnector } from "./joinDateTimeConnector.js";
+import { normalizeDateTime } from "./normalizeDateTime.js";
+// Beyond a week either direction the phrase falls back to an absolute date, as plain
+// `formatCalendar` does.
+const ABS_DAY_THRESHOLD = 6;
+/**
+ * Render a calendar phrase for a moment `diffDays` calendar days from the reference: "tomorrow at
+ * 2:30 PM" within six days, else the long date and time. Shared by the zoned, utc and unix
+ * calendar formatters.
+ *
+ * @param diffDays signed calendar-day distance from the reference, in `timeZone`
+ * @param epochMilliseconds the moment to render
+ * @param timeZone IANA zone the clock time is rendered in
+ * @param locale BCP 47 locale(s) passed through to `Intl`
+ * @param timeStyle the `Intl.DateTimeFormat` time style
+ * @returns the phrase; throws where `Intl` throws, for the caller's sentinel
+ * @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 function formatCalendarDays(diffDays, epochMilliseconds, timeZone, locale, timeStyle) {
+    if (Math.abs(diffDays) > ABS_DAY_THRESHOLD) {
+        return normalizeDateTime(new Intl.DateTimeFormat(locale, {
+            dateStyle: "long",
+            timeStyle,
+            timeZone,
+        }).format(epochMilliseconds));
+    }
+    const dayLabel = new Intl.RelativeTimeFormat(locale, {
+        numeric: "auto",
+    }).format(diffDays, "day");
+    return normalizeDateTime(joinDateTimeConnector(epochMilliseconds, timeZone, locale, dayLabel, timeStyle));
+}
+/**
+ * `formatCalendarDays` for two instants, counting calendar days between their dates in `timeZone`.
+ *
+ * @param target the moment to render
+ * @param reference the moment "today" is read from
+ * @param timeZone IANA zone both dates and the clock time are read in
+ * @param locale BCP 47 locale(s) passed through to `Intl`
+ * @param timeStyle the `Intl.DateTimeFormat` time style
+ * @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 function formatCalendarInstants(target, reference, timeZone, locale, timeStyle) {
+    const targetDate = target.toZonedDateTimeISO(timeZone).toPlainDate();
+    const referenceDate = reference.toZonedDateTimeISO(timeZone).toPlainDate();
+    const diffDays = targetDate.since(referenceDate).days;
+    return formatCalendarDays(diffDays, Number(target.epochMilliseconds), timeZone, locale, timeStyle);
+}

package/dist/internal/formatDateInCalendar.d.ts

@@ -1,47 +1,22 @@
 import type { Temporal } from "@js-temporal/polyfill";
 import type { CalendarSystem } from "../types/index.js";
-import { type CalendarDateStringParts } from "./calendarDateString.js";
 /**
- * Split a Temporal.PlainDate into GMT's calendar-annotated string halves (`{ date, annotation }`)
- * in a known target CalendarSystem — the shared primitive behind both `formatDateInCalendar`
- * (`plain/`) and `internal/calendarZonedString.ts`'s `formatZonedInCalendar` (`zoned/`).
+ * Write a Temporal.PlainDate as a GMT PlainDate string in `calendar`: exactly
+ * `Temporal.PlainDate#toString()` for that date in that calendar. That is Temporal's
+ * `TemporalDateToString` with `calendarName: "auto"` — the ISO date (`PadISOYear`: four digits,
+ * or a sign and six) followed by `FormatCalendarAnnotation`, which is empty for `"iso8601"` and
+ * `[u-ca=<id>]` for every other calendar, `"gregory"` included.
  *
- * The two namespaces need the halves joined differently — `plain/` concatenates them directly,
- * while GMT's zoned grammar splices `T<time><offset>` between them and appends `[<timeZone>]`
- * (see `regex/calendar-zoned-date-time.ts` for why `[u-ca=...]` precedes `[timeZone]`). Sharing
- * the split rather than string-slicing `formatDateInCalendar`'s output on `"["` keeps the era,
- * Ethiopic-family and zero-padding logic in exactly one place per calendar family.
+ * The calendar is passed in, not read from `date.calendarId`, because `"ethiopic"` and
+ * `"coptic"` compute in `"ethioaa"` (`computationCalendarId`); the ISO date is the same whichever
+ * calendar it was computed in.
  *
- * The calendar must always be known up front and passed in explicitly, never re-derived from
- * `date.calendarId` alone: the Ethiopic family ("ethiopic" / "ethiopic-amete-alem" / "coptic")
- * is backed by Temporal's single, ambiguous "ethioaa" id, which cannot tell the three variants
- * apart from the PlainDate object alone (see `ethiopicFamilyCalendar.ts`).
+ * @param date Temporal.PlainDate to write, in any calendar
+ * @param calendar the CalendarSystem the string names
+ * @returns the RFC 9557 PlainDate string
  *
- * @param date Temporal.PlainDate to split, already calendared as `calendar` expects
- *   (`"ethioaa"` for any Ethiopic-family member, its own Temporal calendar id otherwise)
- * @param calendar the CalendarSystem `date` is known to represent
- * @returns `{ date, annotation }` — `annotation` is `""` for the "gregorian"/iso8601 case
- */
-export declare function calendarDateStringParts(date: Temporal.PlainDate, calendar: CalendarSystem): CalendarDateStringParts;
-/**
- * Format a Temporal.PlainDate as a GMT calendar-annotated (or bare ISO) string in a known
- * target CalendarSystem — companion to `calendarSystemOfDateValue`.
- *
- * The calendar must always be known up front and passed in explicitly, never re-derived from
- * `date.calendarId` alone: the Ethiopic family ("ethiopic" / "ethiopic-amete-alem" / "coptic")
- * is backed by Temporal's single, ambiguous "ethioaa" id, which cannot tell the three variants
- * apart from the PlainDate object alone (see `ethiopicFamilyCalendar.ts`).
- *
- * Within a known target calendar, though, the *fields* (year, era, month, day) are always
- * re-derived from the actual resulting `date`, never copied from an input string's tag —
- * `calendarDateParts`/`ethiopicFamilyDateParts` both already do this per-call, which is
- * required because calendar-unit arithmetic can cross a leap-month or era boundary (Hebrew
- * Adar I -> Adar, Japanese Heisei -> Reiwa): a copied tag would describe a date that no longer
- * exists (E5 decision of record D7).
- *
- * @param date Temporal.PlainDate to format, already calendared as `calendar` expects
- *   (`"ethioaa"` for any Ethiopic-family member, its own Temporal calendar id otherwise)
- * @param calendar the CalendarSystem `date` is known to represent
- * @returns GMT's calendar-annotated (or bare ISO, for "gregorian") PlainDate string
+ * @example formatDateInCalendar(Temporal.PlainDate.from("2024-10-03").withCalendar("hebrew"), "hebrew") // "2024-10-03[u-ca=hebrew]"
+ * @example formatDateInCalendar(Temporal.PlainDate.from("2024-10-03"), "iso8601") // "2024-10-03"
+ * @example formatDateInCalendar(Temporal.PlainDate.from("+275760-09-13"), "roc") // "+275760-09-13[u-ca=roc]"
  */
 export declare function formatDateInCalendar(date: Temporal.PlainDate, calendar: CalendarSystem): string;

package/dist/internal/formatDateInCalendar.js

@@ -1,54 +1,23 @@
-import { calendarDateParts, } from "./calendarDateString.js";
-import { ethiopicFamilyDateParts, isEthiopicFamilyCalendar, } from "./ethiopicFamilyCalendar.js";
 /**
- * Split a Temporal.PlainDate into GMT's calendar-annotated string halves (`{ date, annotation }`)
- * in a known target CalendarSystem — the shared primitive behind both `formatDateInCalendar`
- * (`plain/`) and `internal/calendarZonedString.ts`'s `formatZonedInCalendar` (`zoned/`).
+ * Write a Temporal.PlainDate as a GMT PlainDate string in `calendar`: exactly
+ * `Temporal.PlainDate#toString()` for that date in that calendar. That is Temporal's
+ * `TemporalDateToString` with `calendarName: "auto"` — the ISO date (`PadISOYear`: four digits,
+ * or a sign and six) followed by `FormatCalendarAnnotation`, which is empty for `"iso8601"` and
+ * `[u-ca=<id>]` for every other calendar, `"gregory"` included.
  *
- * The two namespaces need the halves joined differently — `plain/` concatenates them directly,
- * while GMT's zoned grammar splices `T<time><offset>` between them and appends `[<timeZone>]`
- * (see `regex/calendar-zoned-date-time.ts` for why `[u-ca=...]` precedes `[timeZone]`). Sharing
- * the split rather than string-slicing `formatDateInCalendar`'s output on `"["` keeps the era,
- * Ethiopic-family and zero-padding logic in exactly one place per calendar family.
+ * The calendar is passed in, not read from `date.calendarId`, because `"ethiopic"` and
+ * `"coptic"` compute in `"ethioaa"` (`computationCalendarId`); the ISO date is the same whichever
+ * calendar it was computed in.
  *
- * The calendar must always be known up front and passed in explicitly, never re-derived from
- * `date.calendarId` alone: the Ethiopic family ("ethiopic" / "ethiopic-amete-alem" / "coptic")
- * is backed by Temporal's single, ambiguous "ethioaa" id, which cannot tell the three variants
- * apart from the PlainDate object alone (see `ethiopicFamilyCalendar.ts`).
+ * @param date Temporal.PlainDate to write, in any calendar
+ * @param calendar the CalendarSystem the string names
+ * @returns the RFC 9557 PlainDate string
  *
- * @param date Temporal.PlainDate to split, already calendared as `calendar` expects
- *   (`"ethioaa"` for any Ethiopic-family member, its own Temporal calendar id otherwise)
- * @param calendar the CalendarSystem `date` is known to represent
- * @returns `{ date, annotation }` — `annotation` is `""` for the "gregorian"/iso8601 case
- */
-export function calendarDateStringParts(date, calendar) {
-    if (isEthiopicFamilyCalendar(calendar)) {
-        return ethiopicFamilyDateParts(date, calendar);
-    }
-    return calendarDateParts(date);
-}
-/**
- * Format a Temporal.PlainDate as a GMT calendar-annotated (or bare ISO) string in a known
- * target CalendarSystem — companion to `calendarSystemOfDateValue`.
- *
- * The calendar must always be known up front and passed in explicitly, never re-derived from
- * `date.calendarId` alone: the Ethiopic family ("ethiopic" / "ethiopic-amete-alem" / "coptic")
- * is backed by Temporal's single, ambiguous "ethioaa" id, which cannot tell the three variants
- * apart from the PlainDate object alone (see `ethiopicFamilyCalendar.ts`).
- *
- * Within a known target calendar, though, the *fields* (year, era, month, day) are always
- * re-derived from the actual resulting `date`, never copied from an input string's tag —
- * `calendarDateParts`/`ethiopicFamilyDateParts` both already do this per-call, which is
- * required because calendar-unit arithmetic can cross a leap-month or era boundary (Hebrew
- * Adar I -> Adar, Japanese Heisei -> Reiwa): a copied tag would describe a date that no longer
- * exists (E5 decision of record D7).
- *
- * @param date Temporal.PlainDate to format, already calendared as `calendar` expects
- *   (`"ethioaa"` for any Ethiopic-family member, its own Temporal calendar id otherwise)
- * @param calendar the CalendarSystem `date` is known to represent
- * @returns GMT's calendar-annotated (or bare ISO, for "gregorian") PlainDate string
+ * @example formatDateInCalendar(Temporal.PlainDate.from("2024-10-03").withCalendar("hebrew"), "hebrew") // "2024-10-03[u-ca=hebrew]"
+ * @example formatDateInCalendar(Temporal.PlainDate.from("2024-10-03"), "iso8601") // "2024-10-03"
+ * @example formatDateInCalendar(Temporal.PlainDate.from("+275760-09-13"), "roc") // "+275760-09-13[u-ca=roc]"
  */
 export function formatDateInCalendar(date, calendar) {
-    const { date: datePart, annotation } = calendarDateStringParts(date, calendar);
-    return `${datePart}${annotation}`;
+    const iso = date.withCalendar("iso8601").toString();
+    return calendar === "iso8601" ? iso : `${iso}[u-ca=${calendar}]`;
 }

package/dist/internal/formatRelativeDuration.d.ts

@@ -0,0 +1,27 @@
+import type { Temporal } from "@js-temporal/polyfill";
+import type { RelativeRoundingMethod, RelativeTimeFormatOptions, RelativeUnit } from "../types/index.js";
+/** A relative unit, singular or plural (`Intl.RelativeTimeFormat` and Temporal accept both). */
+type RelativeUnitName = RelativeUnit | `${RelativeUnit}s`;
+/** The display fields every seven-unit `formatRelative*` function reads. */
+export interface RelativeDurationFormatOptions {
+    style?: RelativeTimeFormatOptions["style"];
+    numeric?: RelativeTimeFormatOptions["numeric"];
+    largestUnit?: RelativeUnitName;
+    roundingMethod?: RelativeRoundingMethod;
+}
+/**
+ * Render a signed distance with `Intl.RelativeTimeFormat`, picking the unit from the distance when
+ * `largestUnit` is omitted. The shared tail of the plain, utc, unix and zoned relative formatters.
+ *
+ * @param diff the signed distance (target since reference)
+ * @param locale BCP 47 locale(s) passed through to `Intl.RelativeTimeFormat`
+ * @param options display style, numeric mode, largest unit and rounding method
+ * @param calendarTotal the total in `unit` against the caller's anchor; called only when the unit
+ *   is calendrical (month, year) and `diff.total(unit)` throws without a `relativeTo`
+ * @returns the formatted phrase; throws where `Intl` or Temporal throws, for the caller's sentinel
+ * @example formatRelativeDuration(Temporal.Duration.from({ minutes: -30 }), "en-US", {}, () => 0) // "30 minutes ago"
+ * @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 {};

package/dist/internal/formatRelativeDuration.js

@@ -0,0 +1,45 @@
+import { normalizeDateTime } from "./normalizeDateTime.js";
+import { resolveRelativeRounding } from "./resolveRelativeRounding.js";
+// Seconds up to a day, then formatRelativeDate's day thresholds (7, 28 and 365 days).
+const SECONDS_PER_DAY = 86_400;
+const AUTO_UNITS = [
+    { unit: "second", maxSeconds: 60 },
+    { unit: "minute", maxSeconds: 3_600 },
+    { unit: "hour", maxSeconds: SECONDS_PER_DAY },
+    { unit: "day", maxSeconds: 7 * SECONDS_PER_DAY },
+    { unit: "week", maxSeconds: 28 * SECONDS_PER_DAY },
+    { unit: "month", maxSeconds: 365 * SECONDS_PER_DAY },
+    { unit: "year", maxSeconds: Infinity },
+];
+/**
+ * Render a signed distance with `Intl.RelativeTimeFormat`, picking the unit from the distance when
+ * `largestUnit` is omitted. The shared tail of the plain, utc, unix and zoned relative formatters.
+ *
+ * @param diff the signed distance (target since reference)
+ * @param locale BCP 47 locale(s) passed through to `Intl.RelativeTimeFormat`
+ * @param options display style, numeric mode, largest unit and rounding method
+ * @param calendarTotal the total in `unit` against the caller's anchor; called only when the unit
+ *   is calendrical (month, year) and `diff.total(unit)` throws without a `relativeTo`
+ * @returns the formatted phrase; throws where `Intl` or Temporal throws, for the caller's sentinel
+ * @example formatRelativeDuration(Temporal.Duration.from({ minutes: -30 }), "en-US", {}, () => 0) // "30 minutes ago"
+ * @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 function formatRelativeDuration(diff, locale, options, calendarTotal) {
+    const absSeconds = Math.abs(diff.total("second"));
+    const unit = options.largestUnit === undefined
+        ? (AUTO_UNITS.find((t) => absSeconds < t.maxSeconds)?.unit ?? "year")
+        : options.largestUnit;
+    let amount;
+    try {
+        amount = resolveRelativeRounding(diff.total(unit), options.roundingMethod);
+    }
+    catch {
+        // month/year are calendrical and need a relativeTo anchor.
+        amount = resolveRelativeRounding(calendarTotal(unit), options.roundingMethod);
+    }
+    return normalizeDateTime(new Intl.RelativeTimeFormat(locale, {
+        numeric: options.numeric === undefined ? "auto" : options.numeric,
+        style: options.style === undefined ? "long" : options.style,
+    }).format(amount, unit));
+}

package/dist/internal/getLocaleFirstDayOfWeek.d.ts

@@ -1,11 +1,14 @@
+import type { LocalesArgument } from "./resolveLocale.js";
 /**
  * Resolve the ISO day-of-week number (1 = Monday .. 7 = Sunday) that a
- * locale considers the first day of the week, via
- * `Intl.Locale.prototype.weekInfo`.
+ * locale considers the first day of the week, from its CLDR week data
+ * (`Intl.Locale#getWeekInfo`, or the older `weekInfo` accessor — see
+ * `localeWeekInfo`).
  *
- * - Returns `null` if `locale` is not a valid BCP 47 tag.
+ * - Returns `null` if `locale` is not a well-formed BCP 47 tag; a well-formed tag with no
+ *   locale data does not throw, so it does not return `null` either.
  * - Falls back to `1` (Monday, matching GMT's existing ISO default in
- *   `startOfDate`/`startOfZoned`) if `weekInfo` is unavailable on the
- *   runtime (older engines) or unresolvable for the given locale.
+ *   `startOfDate`/`startOfZoned`) if the runtime exposes no week data or
+ *   none for the given locale.
  */
-export declare function getLocaleFirstDayOfWeek(locale: string): number | null;
+export declare function getLocaleFirstDayOfWeek(locale: LocalesArgument): number | null;

package/dist/internal/getLocaleFirstDayOfWeek.js

@@ -1,20 +1,19 @@
-// `Intl.Locale.prototype.weekInfo`'s ambient type augmentation lives in
-// `getLocaleWeekendDays.ts` (TS's lib.d.ts doesn't declare it as of TS 5.9).
-// Declared once there; this file relies on that global augmentation rather
-// than redeclaring it.
+import { localeWeekInfo } from "./localeWeekInfo.js";
 /**
  * Resolve the ISO day-of-week number (1 = Monday .. 7 = Sunday) that a
- * locale considers the first day of the week, via
- * `Intl.Locale.prototype.weekInfo`.
+ * locale considers the first day of the week, from its CLDR week data
+ * (`Intl.Locale#getWeekInfo`, or the older `weekInfo` accessor — see
+ * `localeWeekInfo`).
  *
- * - Returns `null` if `locale` is not a valid BCP 47 tag.
+ * - Returns `null` if `locale` is not a well-formed BCP 47 tag; a well-formed tag with no
+ *   locale data does not throw, so it does not return `null` either.
  * - Falls back to `1` (Monday, matching GMT's existing ISO default in
- *   `startOfDate`/`startOfZoned`) if `weekInfo` is unavailable on the
- *   runtime (older engines) or unresolvable for the given locale.
+ *   `startOfDate`/`startOfZoned`) if the runtime exposes no week data or
+ *   none for the given locale.
  */
 export function getLocaleFirstDayOfWeek(locale) {
     try {
-        const weekInfo = new Intl.Locale(locale).weekInfo;
+        const weekInfo = localeWeekInfo(locale);
         if (!weekInfo || typeof weekInfo.firstDay !== "number") {
             return 1;
         }