@northguild/gmt 1.14.2 → 1.16.0

package/dist/internal/calendarZonedPairPolicy.js

@@ -2,38 +2,27 @@ import { calendarSystemOfZonedValue } from "./calendarValueOfZoned.js";
 import { parseCalendarZonedValue } from "./calendarZonedString.js";
 /**
  * Parse two GMT ZonedDateTime values for calendar-unit arithmetic (diff, count, length,
- * split-by-unit): measure in the endpoints' shared calendar when both match, fall back to
- * Gregorian/ISO otherwise, rather than rejecting outright. The zoned sibling of
- * `calendarDatePairPolicy.ts`'s `parseCalendarDatePairForArithmetic` (E5 decision D5).
+ * split-by-unit): both must name the same calendar, which the pair is measured in. The zoned
+ * sibling of `calendarDatePairPolicy.ts`'s `parseCalendarDatePairForArithmetic`.
  *
- * The fallback is MORE load-bearing here than in `plain/`, not less.
- * `Temporal.PlainDate.prototype.until` throws across mismatched calendars only for date units;
- * `Temporal.ZonedDateTime.prototype.until` throws for EVERY `largestUnit` — verified, including
- * `"hour"` and `"nanosecond"`. Without this policy, `diffZoned(hebrewValue, islamicValue,
- * "hours")` would return `null` for a question that has nothing to do with either calendar.
+ * Follows TC39 Temporal's `DifferenceTemporalZonedDateTime`: when `CalendarEquals` is false it
+ * throws a RangeError, for every `largestUnit`, `"hour"` and `"nanosecond"` included (native
+ * Temporal agrees). Calendars are compared by their canonical id; a bare ISO string names
+ * `iso8601`. Callers catch the throw and return their sentinel. (Before 1.16.0 the pair fell
+ * back to ISO; ordering-only functions still accept mixed calendars, because
+ * `Temporal.ZonedDateTime.compare` has no calendar check.)
  *
- * **Consume the returned `a`/`b`, never the values you parsed them from.** The returned operands
- * are already normalized to the resolved calendar, and every downstream use — including a
- * `Temporal.Duration.prototype.total` `relativeTo` anchor — has to be the normalized one. Feeding
- * a raw calendar-tagged operand to `relativeTo` while measuring in ISO does NOT throw; it returns
- * a plausible-looking wrong number (verified: 12.586… where the correct ISO answer is 12.5666…
- * and the correct Hebrew answer is 13), which no sanity check would catch.
- *
- * Throws if either value fails to parse as a valid GMT ZonedDateTime string — callers are
- * expected to have already validated both values (e.g. via `isValidCalendarZonedDateTime`) before
- * calling this, consistent with GMT's existing gate-then-parse-inside-try structure.
+ * Throws if either value fails to parse as a valid GMT ZonedDateTime string, or if the calendars
+ * differ — callers validate both values first (e.g. via `isValidCalendarZonedDateTime`) and wrap
+ * this in try-catch, consistent with GMT's gate-then-parse-inside-try structure.
  */
 export function parseCalendarZonedPairForArithmetic(aValue, bValue) {
     const calendarA = calendarSystemOfZonedValue(aValue);
     const calendarB = calendarSystemOfZonedValue(bValue);
     const a = parseCalendarZonedValue(aValue);
     const b = parseCalendarZonedValue(bValue);
-    if (calendarA && calendarB && calendarA === calendarB) {
-        return { calendar: calendarA, a, b };
+    if (!calendarA || calendarA !== calendarB) {
+        throw new RangeError(`Mismatched calendars: ${String(calendarA)} and ${String(calendarB)}`);
     }
-    return {
-        calendar: "gregorian",
-        a: a.withCalendar("iso8601"),
-        b: b.withCalendar("iso8601"),
-    };
+    return { calendar: calendarA, a, b };
 }

package/dist/internal/calendarZonedString.d.ts

@@ -1,77 +1,53 @@
-import { Temporal } from "@js-temporal/polyfill";
+import type { Temporal } from "@js-temporal/polyfill";
 import type { CalendarSystem, Disambiguation, Offset } from "../types/index.js";
 /**
- * Parse a bare ISO ZonedDateTime string or a GMT calendar-annotated ZonedDateTime string
- * (`"5784-06-15T14:30:00-05:00[u-ca=hebrew][America/New_York]"`, calendar-native fields, not
- * Temporal's own ISO-digit `[u-ca=...]` annotation convention) into a Temporal.ZonedDateTime.
- * Throws on invalid input — callers wrap this in try-catch per GMT's sentinel-return contract.
- *
- * The regex only proves shape; the real construction and validation happen in Temporal —
- * `parseCalendarDateValue` (`Temporal.PlainDate.from(fields, { overflow: "reject" })`) for the
- * calendar-native date half, and `Temporal.ZonedDateTime.from` for the recomposed ISO string
- * (which rejects unknown zones, stale offsets, and out-of-range times). See
- * `context/coding-standards.md`'s scoped manual-string-parsing exception, rule 2.
- *
- * ---------------------------------------------------------------------------------------
- * WHY THE DATE HALF IS FIELD-DECOMPOSED AND HANDED BACK TO TEMPORAL AS ISO DIGITS
- * ---------------------------------------------------------------------------------------
- * The `;era=` suffix can NEVER round-trip through Temporal, at any segment ordering, because it
- * is not valid RFC 9557 at all — `Temporal.PlainDate.from("0006-10-03[u-ca=japanese;era=reiwa]")`
- * throws `RangeError: invalid RFC 9557 string`, and so does every `Temporal.*.from` entry point
- * given the same suffix. Era-bearing calendars ("japanese", "ethiopic") therefore have to be
- * decomposed into `{ era, eraYear, month, day }` and constructed field-wise, which is exactly
- * what `parseCalendarDateValue` already does for the plain case — this function delegates the
- * whole date half to it rather than reimplementing era handling, the Ethiopic-family "ethioaa"
- * carrier routing, or the GMT-to-Temporal calendar-id mapping.
- *
- * The date half then travels back through Temporal as plain ISO digits
- * (`.withCalendar("iso8601").toString()`), so `Temporal.ZonedDateTime.from` resolves the zone,
- * offset and DST against a string it can actually parse. The calendar is re-attached to the
- * RESULT via `.withCalendar(...)`, which keeps downstream `.add`/`.until`/`.round` calendar-aware
- * (verified: `withTimeZone`/`round`/`with`/`startOfDay`/`toPlainDate` all preserve the tag).
- *
- * `isLeapSecond` runs before anything else, exactly as `isValidZonedDateTime` does: verified that
- * `Temporal.ZonedDateTime.from("2024-06-30T23:59:60+00:00[UTC]")` silently CLAMPS to `:59` rather
- * than throwing, so this guard is load-bearing rather than redundant.
- *
- * @param value bare ISO zoned datetime string, or GMT calendar-annotated zoned datetime string
+ * Parse a GMT ZonedDateTime string into a Temporal.ZonedDateTime, read exactly as
+ * `Temporal.ZonedDateTime.from` reads it (`"2024-02-24T14:30:00-05:00[America/New_York][u-ca=hebrew]"`,
+ * which is what `Temporal.ZonedDateTime#toString()` writes). Throws on invalid input — callers wrap
+ * this in try-catch per GMT's sentinel contract.
+ *
+ * - The part before the first `[` must be GMT's strict ISO 8601 extended shape
+ *   (`zonedDateTimeBody`: `<date>T<time>`, then nothing, `Z` or `±HH:MM[:SS[.fraction]]`), as
+ *   `isValidZonedDateTime` requires. Basic format, a space or lower-case `t`
+ *   separator, a lower-case `z`, an hour-only time or offset and a date without a time throw,
+ *   although `Temporal.ZonedDateTime.from` reads them.
+ * - The digits are ISO. The whole string goes to `zonedDateTimeFrom` (`Temporal.ZonedDateTime.from`,
+ *   correct at the range limits), which validates the date, time, offset, zone and annotations.
+ * - The annotations follow Temporal's ISO grammar (`ParseISODateTime`): the time zone annotation
+ *   comes first, elective unknown annotations (`[foo=bar]`) are ignored, the first `u-ca`
+ *   annotation names the calendar, and an unknown critical annotation or a second `u-ca`
+ *   annotation when either one is critical is rejected. A calendar before the zone and `;era=`
+ *   are not RFC 9557 and Temporal rejects them.
+ * - The calendar id is Temporal's canonical one (`CanonicalizeCalendar`) and must be a
+ *   `CalendarSystem`.
+ * - The result computes in `computationCalendarId(calendar)` (`"ethioaa"` for `"ethiopic"` and
+ *   `"coptic"`), so callers that write a string back take the calendar from
+ *   `calendarSystemOfZonedValue(value)`.
+ * - `isLeapSecond` runs first: `Temporal.ZonedDateTime.from("2024-06-30T23:59:60+00:00[UTC]")`
+ *   clamps to `:59` instead of throwing.
+ *
+ * @param value ISO zoned datetime string, optionally with RFC 9557 annotations after the zone
  * @param options optional Temporal `disambiguation`/`offset`, passed through to
  *   `Temporal.ZonedDateTime.from` so a caller's own DST/offset policy still applies
- * @returns Temporal.ZonedDateTime carrying the annotated calendar (or `iso8601` when bare)
+ * @returns Temporal.ZonedDateTime in the computation calendar (`iso8601` when unannotated)
  */
 export declare function parseCalendarZonedValue(value: string, options?: {
     disambiguation?: Disambiguation;
     offset?: Offset;
 }): Temporal.ZonedDateTime;
 /**
- * Format a Temporal.ZonedDateTime as GMT's calendar-annotated (or bare ISO) zoned string in a
- * known target CalendarSystem — the zoned companion to `formatDateInCalendar`, and the ONLY
- * writer of the calendar-annotated zoned grammar anywhere in GMT.
- *
- * Never call `zdt.toString()` on a calendared value and never compose
- * `` `${zdt.toPlainDateTime()}[${zdt.timeZoneId}]` `` on one either: both emit Temporal's
- * `[timeZone][u-ca=...]` RFC 9557 ordering (verified: a Hebrew-calendared
- * `.toPlainDateTime().toString()` yields `"2024-03-25T14:30:00[u-ca=hebrew]"`), which is exactly
- * the ordering GMT rejects because reading it back misparses the digits as ISO. Route every
- * calendar-annotated zoned output through this function instead.
- *
- * Every field is RE-DERIVED from the actual `zdt` result and nothing but the IANA zone id is
- * copied (E7's D7-zoned, extending E5's D7): a single calendar-unit add can move the era AND the
- * UTC offset at once — verified, Japanese Heisei 31-04-05 in `Africa/Casablanca` `+1 month` lands
- * on Reiwa 1-05-05 inside a DST fold — so a tag or offset copied from the input would describe a
- * moment that no longer exists.
- *
- * Unlike `formatDateInCalendar`, this does NOT require `zdt` to already carry `calendar`'s own
- * Temporal calendar id — it re-calendars the value itself before reading the date fields. That is
- * deliberate: several `zoned/interval/*` functions synthesize boundary points via
- * `Temporal.Instant.prototype.toZonedDateTimeISO`, which always returns an `iso8601`-calendared
- * value. Re-calendaring here means a synthesized boundary can never silently emit a bare ISO
- * string into an otherwise calendar-tagged result set — one class of bug removed by construction
- * rather than by remembering to re-attach the tag at every synthesis site. The instant, wall time
- * and zone are untouched; only which calendar the date fields resolve through changes.
- *
- * @param zdt Temporal.ZonedDateTime to format
- * @param calendar the CalendarSystem to express `zdt`'s date fields in
- * @returns GMT's calendar-annotated (or bare ISO, for "gregorian") zoned datetime string
+ * Write a Temporal.ZonedDateTime as a GMT ZonedDateTime string in `calendar`: exactly
+ * `Temporal.ZonedDateTime#toString()` for that instant, zone and calendar — the ISO date and time,
+ * the offset, `[<timeZone>]`, then `[u-ca=<id>]` for every calendar but `"iso8601"`
+ * (`FormatCalendarAnnotation` with `"auto"`).
+ *
+ * The calendar is passed in rather than read from `zdt.calendarId`: `"ethiopic"` and `"coptic"`
+ * compute in `"ethioaa"`, and boundary points synthesized with
+ * `Temporal.Instant.prototype.toZonedDateTimeISO` are `iso8601`. The instant, wall time and zone
+ * are written as they are; only the annotation names the calendar.
+ *
+ * @param zdt Temporal.ZonedDateTime to write, in any calendar
+ * @param calendar the CalendarSystem the string names
+ * @returns the RFC 9557 zoned datetime string
  */
 export declare function formatZonedInCalendar(zdt: Temporal.ZonedDateTime, calendar: CalendarSystem): string;

package/dist/internal/calendarZonedString.js

@@ -1,120 +1,71 @@
-import { Temporal } from "@js-temporal/polyfill";
 import { isLeapSecond } from "../plain/validate/isLeapSecond.js";
-import { calendarZonedDateTime } from "../regex/index.js";
-import { parseCalendarDateValue } from "./calendarDateString.js";
-import { temporalCalendarIds } from "./calendarSystemIds.js";
-import { isEthiopicFamilyCalendar } from "./ethiopicFamilyCalendar.js";
-import { calendarDateStringParts } from "./formatDateInCalendar.js";
-import { hasCalendarAnnotation } from "./hasCalendarAnnotation.js";
+import { canonicalCalendarSystem, computationCalendarId, } from "./calendarSystemIds.js";
+import { hasZonedDateTimeShape } from "./isoStringBody.js";
+import { zonedDateTimeFrom } from "./zonedWallClock.js";
 /**
- * Parse a bare ISO ZonedDateTime string or a GMT calendar-annotated ZonedDateTime string
- * (`"5784-06-15T14:30:00-05:00[u-ca=hebrew][America/New_York]"`, calendar-native fields, not
- * Temporal's own ISO-digit `[u-ca=...]` annotation convention) into a Temporal.ZonedDateTime.
- * Throws on invalid input — callers wrap this in try-catch per GMT's sentinel-return contract.
+ * Parse a GMT ZonedDateTime string into a Temporal.ZonedDateTime, read exactly as
+ * `Temporal.ZonedDateTime.from` reads it (`"2024-02-24T14:30:00-05:00[America/New_York][u-ca=hebrew]"`,
+ * which is what `Temporal.ZonedDateTime#toString()` writes). Throws on invalid input — callers wrap
+ * this in try-catch per GMT's sentinel contract.
  *
- * The regex only proves shape; the real construction and validation happen in Temporal —
- * `parseCalendarDateValue` (`Temporal.PlainDate.from(fields, { overflow: "reject" })`) for the
- * calendar-native date half, and `Temporal.ZonedDateTime.from` for the recomposed ISO string
- * (which rejects unknown zones, stale offsets, and out-of-range times). See
- * `context/coding-standards.md`'s scoped manual-string-parsing exception, rule 2.
+ * - The part before the first `[` must be GMT's strict ISO 8601 extended shape
+ *   (`zonedDateTimeBody`: `<date>T<time>`, then nothing, `Z` or `±HH:MM[:SS[.fraction]]`), as
+ *   `isValidZonedDateTime` requires. Basic format, a space or lower-case `t`
+ *   separator, a lower-case `z`, an hour-only time or offset and a date without a time throw,
+ *   although `Temporal.ZonedDateTime.from` reads them.
+ * - The digits are ISO. The whole string goes to `zonedDateTimeFrom` (`Temporal.ZonedDateTime.from`,
+ *   correct at the range limits), which validates the date, time, offset, zone and annotations.
+ * - The annotations follow Temporal's ISO grammar (`ParseISODateTime`): the time zone annotation
+ *   comes first, elective unknown annotations (`[foo=bar]`) are ignored, the first `u-ca`
+ *   annotation names the calendar, and an unknown critical annotation or a second `u-ca`
+ *   annotation when either one is critical is rejected. A calendar before the zone and `;era=`
+ *   are not RFC 9557 and Temporal rejects them.
+ * - The calendar id is Temporal's canonical one (`CanonicalizeCalendar`) and must be a
+ *   `CalendarSystem`.
+ * - The result computes in `computationCalendarId(calendar)` (`"ethioaa"` for `"ethiopic"` and
+ *   `"coptic"`), so callers that write a string back take the calendar from
+ *   `calendarSystemOfZonedValue(value)`.
+ * - `isLeapSecond` runs first: `Temporal.ZonedDateTime.from("2024-06-30T23:59:60+00:00[UTC]")`
+ *   clamps to `:59` instead of throwing.
  *
- * ---------------------------------------------------------------------------------------
- * WHY THE DATE HALF IS FIELD-DECOMPOSED AND HANDED BACK TO TEMPORAL AS ISO DIGITS
- * ---------------------------------------------------------------------------------------
- * The `;era=` suffix can NEVER round-trip through Temporal, at any segment ordering, because it
- * is not valid RFC 9557 at all — `Temporal.PlainDate.from("0006-10-03[u-ca=japanese;era=reiwa]")`
- * throws `RangeError: invalid RFC 9557 string`, and so does every `Temporal.*.from` entry point
- * given the same suffix. Era-bearing calendars ("japanese", "ethiopic") therefore have to be
- * decomposed into `{ era, eraYear, month, day }` and constructed field-wise, which is exactly
- * what `parseCalendarDateValue` already does for the plain case — this function delegates the
- * whole date half to it rather than reimplementing era handling, the Ethiopic-family "ethioaa"
- * carrier routing, or the GMT-to-Temporal calendar-id mapping.
- *
- * The date half then travels back through Temporal as plain ISO digits
- * (`.withCalendar("iso8601").toString()`), so `Temporal.ZonedDateTime.from` resolves the zone,
- * offset and DST against a string it can actually parse. The calendar is re-attached to the
- * RESULT via `.withCalendar(...)`, which keeps downstream `.add`/`.until`/`.round` calendar-aware
- * (verified: `withTimeZone`/`round`/`with`/`startOfDay`/`toPlainDate` all preserve the tag).
- *
- * `isLeapSecond` runs before anything else, exactly as `isValidZonedDateTime` does: verified that
- * `Temporal.ZonedDateTime.from("2024-06-30T23:59:60+00:00[UTC]")` silently CLAMPS to `:59` rather
- * than throwing, so this guard is load-bearing rather than redundant.
- *
- * @param value bare ISO zoned datetime string, or GMT calendar-annotated zoned datetime string
+ * @param value ISO zoned datetime string, optionally with RFC 9557 annotations after the zone
  * @param options optional Temporal `disambiguation`/`offset`, passed through to
  *   `Temporal.ZonedDateTime.from` so a caller's own DST/offset policy still applies
- * @returns Temporal.ZonedDateTime carrying the annotated calendar (or `iso8601` when bare)
+ * @returns Temporal.ZonedDateTime in the computation calendar (`iso8601` when unannotated)
  */
 export function parseCalendarZonedValue(value, options) {
     if (isLeapSecond(value)) {
         throw new RangeError(`Leap seconds are not supported: ${value}`);
     }
-    const match = calendarZonedDateTime.exec(value);
-    if (!match) {
-        // Either Temporal's own `[timeZone][u-ca=...]` ordering or a wrong-ordered GMT string. Both
-        // are rejected rather than re-parsed: the former is not GMT's contract (E5 decision D1), and
-        // the latter is the ~3760-year silent-misparse hazard documented in
-        // `regex/calendar-zoned-date-time.ts`. Only a genuinely un-annotated string falls through.
-        if (hasCalendarAnnotation(value)) {
-            throw new RangeError(`Not a valid GMT ZonedDateTime string: ${value}`);
-        }
-        const bare = Temporal.ZonedDateTime.from(value, options);
-        if (bare.timeZoneId.length === 0) {
-            throw new RangeError(`Missing time zone: ${value}`);
-        }
-        return bare;
+    if (!hasZonedDateTimeShape(value)) {
+        throw new RangeError(`Not an extended ISO 8601 zoned date-time: ${String(value)}`);
+    }
+    const zoned = zonedDateTimeFrom(value, options);
+    if (zoned.timeZoneId.length === 0) {
+        throw new RangeError(`Missing time zone: ${value}`);
     }
-    const [, year, month, day, time, offset, calendarId, era, timeZone] = match;
-    const eraSuffix = era ? `;era=${era}` : "";
-    const date = parseCalendarDateValue(`${year}-${month}-${day}[u-ca=${calendarId}${eraSuffix}]`);
-    const isoDate = date.withCalendar("iso8601").toString();
-    const zoned = Temporal.ZonedDateTime.from(`${isoDate}T${time}${offset ?? ""}[${timeZone}]`, options);
-    // Re-attach the calendar the date half resolved to — `date.calendarId` rather than the string's
-    // own tag, so the Ethiopic family lands on its "ethioaa" carrier and GMT ids that differ from
-    // Temporal's ("islamic-tabular" -> "islamic-tbla") map through exactly once, in one place.
-    return zoned.withCalendar(date.calendarId);
+    const calendar = canonicalCalendarSystem(zoned.calendarId);
+    if (!calendar) {
+        throw new RangeError(`Unsupported calendar: ${zoned.calendarId}`);
+    }
+    return zoned.withCalendar(computationCalendarId(calendar));
 }
 /**
- * Format a Temporal.ZonedDateTime as GMT's calendar-annotated (or bare ISO) zoned string in a
- * known target CalendarSystem — the zoned companion to `formatDateInCalendar`, and the ONLY
- * writer of the calendar-annotated zoned grammar anywhere in GMT.
- *
- * Never call `zdt.toString()` on a calendared value and never compose
- * `` `${zdt.toPlainDateTime()}[${zdt.timeZoneId}]` `` on one either: both emit Temporal's
- * `[timeZone][u-ca=...]` RFC 9557 ordering (verified: a Hebrew-calendared
- * `.toPlainDateTime().toString()` yields `"2024-03-25T14:30:00[u-ca=hebrew]"`), which is exactly
- * the ordering GMT rejects because reading it back misparses the digits as ISO. Route every
- * calendar-annotated zoned output through this function instead.
+ * Write a Temporal.ZonedDateTime as a GMT ZonedDateTime string in `calendar`: exactly
+ * `Temporal.ZonedDateTime#toString()` for that instant, zone and calendar — the ISO date and time,
+ * the offset, `[<timeZone>]`, then `[u-ca=<id>]` for every calendar but `"iso8601"`
+ * (`FormatCalendarAnnotation` with `"auto"`).
  *
- * Every field is RE-DERIVED from the actual `zdt` result and nothing but the IANA zone id is
- * copied (E7's D7-zoned, extending E5's D7): a single calendar-unit add can move the era AND the
- * UTC offset at once — verified, Japanese Heisei 31-04-05 in `Africa/Casablanca` `+1 month` lands
- * on Reiwa 1-05-05 inside a DST fold — so a tag or offset copied from the input would describe a
- * moment that no longer exists.
+ * The calendar is passed in rather than read from `zdt.calendarId`: `"ethiopic"` and `"coptic"`
+ * compute in `"ethioaa"`, and boundary points synthesized with
+ * `Temporal.Instant.prototype.toZonedDateTimeISO` are `iso8601`. The instant, wall time and zone
+ * are written as they are; only the annotation names the calendar.
  *
- * Unlike `formatDateInCalendar`, this does NOT require `zdt` to already carry `calendar`'s own
- * Temporal calendar id — it re-calendars the value itself before reading the date fields. That is
- * deliberate: several `zoned/interval/*` functions synthesize boundary points via
- * `Temporal.Instant.prototype.toZonedDateTimeISO`, which always returns an `iso8601`-calendared
- * value. Re-calendaring here means a synthesized boundary can never silently emit a bare ISO
- * string into an otherwise calendar-tagged result set — one class of bug removed by construction
- * rather than by remembering to re-attach the tag at every synthesis site. The instant, wall time
- * and zone are untouched; only which calendar the date fields resolve through changes.
- *
- * @param zdt Temporal.ZonedDateTime to format
- * @param calendar the CalendarSystem to express `zdt`'s date fields in
- * @returns GMT's calendar-annotated (or bare ISO, for "gregorian") zoned datetime string
+ * @param zdt Temporal.ZonedDateTime to write, in any calendar
+ * @param calendar the CalendarSystem the string names
+ * @returns the RFC 9557 zoned datetime string
  */
 export function formatZonedInCalendar(zdt, calendar) {
-    if (calendar === "gregorian") {
-        return zdt.withCalendar("iso8601").toString();
-    }
-    // The whole Ethiopic family computes through "ethioaa" rather than Temporal's own
-    // "ethiopic"/"coptic" ids, which throw under ICU >= 78 — see internal/ethiopicFamilyCalendar.ts.
-    const temporalCalendarId = isEthiopicFamilyCalendar(calendar)
-        ? "ethioaa"
-        : temporalCalendarIds[calendar];
-    const { date, annotation } = calendarDateStringParts(zdt.withCalendar(temporalCalendarId).toPlainDate(), calendar);
-    const time = zdt.toPlainTime().toString();
-    return `${date}T${time}${zdt.offset}${annotation}[${zdt.timeZoneId}]`;
+    const iso = zdt.withCalendar("iso8601").toString();
+    return calendar === "iso8601" ? iso : `${iso}[u-ca=${calendar}]`;
 }

package/dist/internal/compareUnixEpochs.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Compare two unix epoch values as instants, for the unix comparison predicates.
+ *
+ * @param value1 first epoch value (number or digit string)
+ * @param value2 second epoch value
+ * @param options optional `{ epochUnit }` (milliseconds by default; singular names accepted)
+ * @returns `Temporal.Instant.compare`'s -1, 0 or 1, or null when the unit or either value is invalid
+ * @example compareUnixEpochs(0, "1000") // -1
+ * @example compareUnixEpochs("1706659200", 1706659200, { epochUnit: "second" }) // 0
+ * @example compareUnixEpochs(0, 1.5) // null (not an integer epoch)
+ */
+export declare function compareUnixEpochs(value1: unknown, value2: unknown, options?: {
+    epochUnit?: unknown;
+}): number | null;

package/dist/internal/compareUnixEpochs.js

@@ -0,0 +1,25 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { resolveUnixEpochUnit, unixEpochToInstant } from "./unixEpochValue.js";
+/**
+ * Compare two unix epoch values as instants, for the unix comparison predicates.
+ *
+ * @param value1 first epoch value (number or digit string)
+ * @param value2 second epoch value
+ * @param options optional `{ epochUnit }` (milliseconds by default; singular names accepted)
+ * @returns `Temporal.Instant.compare`'s -1, 0 or 1, or null when the unit or either value is invalid
+ * @example compareUnixEpochs(0, "1000") // -1
+ * @example compareUnixEpochs("1706659200", 1706659200, { epochUnit: "second" }) // 0
+ * @example compareUnixEpochs(0, 1.5) // null (not an integer epoch)
+ */
+export function compareUnixEpochs(value1, value2, options) {
+    const epochUnit = resolveUnixEpochUnit(options?.epochUnit);
+    if (epochUnit === null) {
+        return null;
+    }
+    const instant1 = unixEpochToInstant(value1, epochUnit);
+    const instant2 = unixEpochToInstant(value2, epochUnit);
+    if (instant1 === null || instant2 === null) {
+        return null;
+    }
+    return Temporal.Instant.compare(instant1, instant2);
+}

package/dist/internal/dateTimeUnitHelpers.d.ts

@@ -25,3 +25,21 @@ export declare function getStartOfDateTimeUnit(source: Temporal.PlainDateTime, u
  * @returns new Temporal.PlainDateTime advanced by the specified amount
  */
 export declare function addDateTimeUnit(date: Temporal.PlainDateTime, unit: string, amount: number): Temporal.PlainDateTime;
+/**
+ * Return the start of the date `unit` after the one containing `source`.
+ *
+ * - Steps one unit first and truncates after, so `source`'s own start is never materialised: the
+ *   first representable PlainDateTime is `-271821-04-19T00:00:00.000000001`, so even the day
+ *   holding it began before the range, while the next day's midnight did not.
+ * - Year, month and week step by that unit (weeks start on Monday, like `getStartOfDateTimeUnit`);
+ *   every other unit steps to the next midnight, matching `getStartOfDateTimeUnit`'s day default.
+ * - Does NOT validate the unit — caller ensures it is a DateTimeUnit.
+ *
+ * @param source Temporal.PlainDateTime inside the current unit
+ * @param unit DateTimeUnit to step by
+ * @returns Temporal.PlainDateTime at the start of the next unit
+ *
+ * @example getStartOfNextDateTimeUnit(Temporal.PlainDateTime.from("2024-03-15T14:30:45"), "week") // 2024-03-18T00:00:00
+ * @example getStartOfNextDateTimeUnit(Temporal.PlainDateTime.from("-271821-04-19T12:00:00"), "day") // -271821-04-20T00:00:00
+ */
+export declare function getStartOfNextDateTimeUnit(source: Temporal.PlainDateTime, unit: string): Temporal.PlainDateTime;

package/dist/internal/dateTimeUnitHelpers.js

@@ -48,3 +48,30 @@ export function addDateTimeUnit(date, unit, amount) {
             return date;
     }
 }
+/**
+ * Return the start of the date `unit` after the one containing `source`.
+ *
+ * - Steps one unit first and truncates after, so `source`'s own start is never materialised: the
+ *   first representable PlainDateTime is `-271821-04-19T00:00:00.000000001`, so even the day
+ *   holding it began before the range, while the next day's midnight did not.
+ * - Year, month and week step by that unit (weeks start on Monday, like `getStartOfDateTimeUnit`);
+ *   every other unit steps to the next midnight, matching `getStartOfDateTimeUnit`'s day default.
+ * - Does NOT validate the unit — caller ensures it is a DateTimeUnit.
+ *
+ * @param source Temporal.PlainDateTime inside the current unit
+ * @param unit DateTimeUnit to step by
+ * @returns Temporal.PlainDateTime at the start of the next unit
+ *
+ * @example getStartOfNextDateTimeUnit(Temporal.PlainDateTime.from("2024-03-15T14:30:45"), "week") // 2024-03-18T00:00:00
+ * @example getStartOfNextDateTimeUnit(Temporal.PlainDateTime.from("-271821-04-19T12:00:00"), "day") // -271821-04-20T00:00:00
+ */
+export function getStartOfNextDateTimeUnit(source, unit) {
+    switch (unit) {
+        case "year":
+        case "month":
+        case "week":
+            return getStartOfDateTimeUnit(addDateTimeUnit(source, unit, 1), unit);
+        default:
+            return source.add({ days: 1 }).withPlainTime();
+    }
+}

package/dist/internal/dateUnitHelpers.d.ts

@@ -3,16 +3,19 @@ import type { Temporal } from "@js-temporal/polyfill";
  * Return the start of the specified date `unit` for a `Temporal.PlainDate`.
  *
  * - Always uses Monday as the week start (consistent with roundDate semantics).
+ * - Works in `source`'s own calendar (a Hebrew month starts on its day 1).
  * - Does NOT validate the unit — caller ensures it is a DateUnit.
  *
  * @param source Temporal.PlainDate to round
  * @param unit DateUnit to specify the unit for the start
- * @returns Temporal.PlainDate at the start of the specified unit
+ * @returns Temporal.PlainDate at the start of the specified unit; throws RangeError when it lies
+ *   before the representable range
  */
 export declare function getStartOfDateUnit(source: Temporal.PlainDate, unit: string): Temporal.PlainDate;
 /**
  * Add `amount` units of the specified date `unit` to a `Temporal.PlainDate`.
  *
+ * - Calendar units resolve in `source`'s calendar through the Temporal compat layer.
  * - Does NOT validate the unit — caller ensures it is a DateUnit.
  *
  * @param date Temporal.PlainDate to advance
@@ -21,3 +24,38 @@ export declare function getStartOfDateUnit(source: Temporal.PlainDate, unit: str
  * @returns new Temporal.PlainDate advanced by the specified amount
  */
 export declare function addDateUnit(date: Temporal.PlainDate, unit: string, amount: number): Temporal.PlainDate;
+/**
+ * Return the start of the date `unit` after the one containing `source`.
+ *
+ * - Steps one unit first and truncates after, so `source`'s own start is never materialised: the
+ *   month holding the first representable date (`-271821-04-19`) began before the range, while the
+ *   next month's start did not. Both orders agree everywhere else, because a one-unit step clamps
+ *   within the next unit (Jan 31 + 1 month = Feb 29, whose month starts on Feb 1).
+ * - Always uses Monday as the week start, like `getStartOfDateUnit`.
+ * - Does NOT validate the unit — caller ensures it is a DateUnit.
+ *
+ * @param source Temporal.PlainDate inside the current unit
+ * @param unit DateUnit to step by
+ * @returns Temporal.PlainDate at the start of the next unit
+ *
+ * @example getStartOfNextDateUnit(Temporal.PlainDate.from("2024-01-31"), "month") // 2024-02-01
+ * @example getStartOfNextDateUnit(Temporal.PlainDate.from("-271821-04-19"), "month") // -271821-05-01
+ */
+export declare function getStartOfNextDateUnit(source: Temporal.PlainDate, unit: string): Temporal.PlainDate;
+/**
+ * Return the whole days from the start of the date `unit` containing `source` to `source`.
+ *
+ * - Read from the calendar fields, so the unit's start is never materialised (it may lie before
+ *   the representable range).
+ * - Always uses Monday as the week start, like `getStartOfDateUnit`. A day unit is 0 days in.
+ * - Accepts a `Temporal.PlainDate` or a `Temporal.PlainDateTime` (only its date matters).
+ * - Does NOT validate the unit — caller ensures it is a DateUnit.
+ *
+ * @param source value with calendar date fields, read in its own calendar
+ * @param unit DateUnit to measure within
+ * @returns number of whole days since the unit started
+ *
+ * @example getDaysIntoDateUnit(Temporal.PlainDate.from("2024-03-13"), "month") // 12
+ * @example getDaysIntoDateUnit(Temporal.PlainDate.from("2024-03-13"), "week") // 2 (a Wednesday)
+ */
+export declare function getDaysIntoDateUnit(source: Pick<Temporal.PlainDate, "day" | "dayOfWeek" | "dayOfYear">, unit: string): number;