# @burglekitt/gmt > ## ⚠️ Deprecation Notice > > This package has moved. **`gmt` is now published as > [`@northguild/gmt`](https://www.npmjs.com/package/@northguild/gmt)** under the > [northguild](https://github.com/northguild) GitHub organization. > > - **New repository:** > - **New package:** `@northguild/gmt` > > `@burglekitt/gmt` is deprecated and will receive no further updates. Please > migrate to `@northguild/gmt`. Give Me Temporal. `@burglekitt/gmt` is a Temporal-first date and time library with a simple rule set: - ISO 8601 strings in - ISO 8601 strings, numbers, booleans, or arrays out - no `Date` - plain and zoned operations kept separate It wraps `@js-temporal/polyfill` behind a smaller, more opinionated API aimed at the cases application code actually hits: arithmetic, comparison, parsing, formatting, unix conversions, timezone conversion, and validation. **Status:** pre-alpha. Expect API movement while the surface is still being filled out. ## Install ```bash npm install @burglekitt/gmt ``` ```bash pnpm add @burglekitt/gmt ``` ## Design Philosophy GMT enforces a strict input/output contract to keep behavior predictable and auditable: - **Explicit inputs only**: Public APIs accept clearly defined shapes — ISO 8601 date/time strings, IANA timezone identifiers, or numeric Unix epoch values (explicitly seconds or milliseconds). We do not attempt to parse arbitrary or ambiguous date formats. - **Predictable outputs**: Helpers return normalized values (ISO strings, numbers, booleans, or arrays). Invalid input yields typed fallbacks (`""`, `null`, or `false`) instead of throwing. - **No fuzzy parsing**: Avoid "throw everything at the wall" patterns found in permissive libraries. If you need permissive parsing, perform it outside of `@burglekitt/gmt` and then canonicalize to the strict shapes before calling into gmt. - **Developer comfort with standards**: The library's goal is to make developers comfortable and deliberate with ISO 8601, IANA timezones, UTC instants, and Unix epochs by keeping APIs small and explicit. ## Core Rules | Rule | Current behavior | | ----------------------- | ---------------------------------------------------------------------------------- | | String-first API | Public helpers consume ISO strings and return normalized strings where appropriate | | Temporal-only internals | `Temporal` does the parsing and timezone math | | Plain/zoned separation | `plain/*` is timezone-free, `zoned/*` is timezone-aware | | No-throw public helpers | Invalid input returns a typed fallback instead of throwing | Invalid input fallbacks are consistent across the library: - string-returning helpers return `""` - number-returning helpers return `null` - boolean-returning helpers return `false` - array-returning helpers return `[]` ## Testing Every function is exercised across **17 locales** and a full IANA timezone matrix. The CI pipeline runs the complete suite in **20 environments** — 2 Node versions (22, 24) × 10 timezones spanning every UTC offset band from Pacific/Niue (−11:00) to Pacific/Apia (+13:00): | Timezone | UTC Offset | | ------------------- | --------------- | | Pacific/Niue | −11:00 | | America/New_York | −05:00 / −04:00 | | UTC | ±00:00 | | Europe/London | ±00:00 / +01:00 | | Asia/Kolkata | +05:30 | | Asia/Kathmandu | +05:45 | | Asia/Shanghai | +08:00 | | Australia/Lord_Howe | +10:00 / +11:00 | | Pacific/Chatham | +12:45 / +13:45 | | Pacific/Apia | +13:00 / +14:00 | This guarantees that DST transitions, leap seconds, half-hour offsets, and locale-specific weekend boundaries are all covered — not just the happy path. ### Testing strategy GMT's test suite balances **thoroughness** against **maintenance burden** by testing behavior, not permutations. **What we test exhaustively:** - **17-locale matrix** — every locale-aware function is exercised across all 17 `MustTestLocales` (en-US, en-GB, de-DE, fr-FR, es-ES, it-IT, pt-PT, sv-SE, zh-CN, zh-TW, ja-JP, ko-KR, ar-SA, he-IL, ru-RU, tr-TR, is-IS). This covers script direction, first-day-of-week differences, and calendar metadata. - **Timezone battle matrix** — every zoned function is exercised across 10 IANA timezones spanning every UTC offset band from Pacific/Niue (−11:00) to Pacific/Apia (+14:00), including DST-transition and half-hour-offset zones. - **Zero-length and identity cases** — every interval and arithmetic function is tested with zero-length inputs, identity operations, and boundary-adjacent values. - **Invalid-input sentinels** — every public function is tested for the documented fallback behavior (`""`, `null`, `false`, `[]`) on malformed strings, wrong types, leap seconds, and inverted intervals. **What we collapse:** - **Non-string input tables** — functions that guard with `typeof x !== "string"` return the same sentinel for `null`, `undefined`, `123`, `true`, `[]`, and `{}`. We test one representative non-string per argument position rather than all six types × N positions. The collapse is safe because all non-string types hit the identical early-return code path. - **Redundant permutations** — adjacent/disjoint/reversed interval cases that produce identical results are not duplicated across every function variant. The `plain/`, `zoned/`, `utc/`, and `unix/` families share the same mathematical behavior; each family gets the minimum set of cases needed to prove correctness. **Result:** 15,611 tests across 527 files that exercise real behavior differences without redundant permutations. The suite runs in CI as 312,220 executions (15,611 × 2 Node versions × 10 timezones). ## How GMT is tested, vs. the libraries it targets GMT's roadmap (see [context/roadmap](https://github.com/burglekitt/gmt/tree/main/context/roadmap)) is explicitly scoped against react-aria's **`@internationalized/date`**, **Luxon**, **date-fns**, and **Moment.js** — the same four libraries compared below. All numbers were verified **2026-08-22** against the exact package versions/commits below — nothing is estimated. Re-verify before citing these numbers elsewhere; library surfaces and CI configs move. | Library | Version tested | | ------------------------- | --------------------------------------- | | GMT (`@burglekitt/gmt`) | 1.12.0 | | `@internationalized/date` | 3.12.3 (`adobe/react-spectrum@5d191ab`) | | Luxon | 3.7.2 (`moment/luxon@f427515`) | | date-fns | 4.4.0 (`date-fns/date-fns@a0a3922`) | | Moment.js | 2.30.1 (`moment/moment@cf524af`) | | Metric | GMT | `@internationalized/date` | Luxon | date-fns | Moment.js | | ------------------------------- | -------------------------------------------------- | ------------------------------ | ------------------------------------ | ----------------------------------------- | -------------------------------- | | Test files | 527 | 6 | 58 / 60
(2 didn't run
locally) | 256 | 191
(52 core +
139 locale) | | Individual test cases | **15,611** | 386 | 1,222 | 3,213 | 3,901 | | Effective CI test
executions | **312,220**
(15,611 × 2 Node
× 10 timezones) | 386
(×1 Node) | 4,888
(1,222 × 4 Node) | 3,213
(×1 Node) | 11,703
(3,901 × 3 Node) | | CI Node.js matrix | 22, 24 | n/a — tests
React 16–canary | 20, 22, 24, 25 | not explicit
(`node = "latest"`) | LTS, LTS-1,
latest | | CI timezone matrix | **10 zones × 2**
**Node, full suite** | none found | none found | dedicated workflow,
zone scope unclear | 6 zones,
partial suite only | | Locale test matrix | **17 locales**,
every locale fn | none found | none found | none found | none found | | Real-browser CI | not yet | yes (Playwright) | not found | yes (Playwright) | not found | | Maintenance | active | active | active | active | **maintenance
mode** | Methodology: "Test files" and the CI/maintenance rows come from each project's public CI configuration and repository file listing. "Individual test cases" for GMT, Luxon, date-fns, and Moment.js were obtained by actually cloning the repo at the commit above, installing dependencies, running the project's own test command (`vitest run` / `jest` / `node scripts/test.js`), and reading that runner's own final summary — not grepped from source. `@internationalized/date` was run by cloning `adobe/react-spectrum` at `5d191ab`, installing dependencies, and executing `npx jest packages/@internationalized/date/tests/`, yielding 386 passing tests. Luxon (39 failures) and date-fns (46 failures) had environment-dependent local failures that don't affect the total count: Luxon's suite assumes its CI container's local time zone is `America/New_York`; date-fns's experimental native-`Temporal` code path needs a global `Temporal` Node doesn't yet provide natively. Moment.js passed cleanly (0 failed) on Node 24. Sources: [GMT](https://github.com/burglekitt/gmt/blob/main/.github/workflows/ci.yml) · [`@internationalized/date`](https://github.com/adobe/react-spectrum/blob/main/.circleci/config.yml) · [Luxon](https://github.com/moment/luxon/blob/master/.github/workflows/test.yml) · [date-fns](https://github.com/date-fns/date-fns/tree/main/.github/workflows) · [Moment.js](https://github.com/moment/moment/tree/develop/.github/workflows). ### Functionality parity progress GMT's roadmap tracks parity against the same four libraries story-by-story, with each gap sourced against the specific competitor function it closes — see [context/roadmap](https://github.com/burglekitt/gmt/tree/main/context/roadmap) for the full, source-verified audit trail. This is a live snapshot, not a finished-parity claim: ✅ shipped, 🟡 in progress, ⏳ backlog and not yet scheduled. | Capability | Status | Also has it | | -------------------------------------------------------------------------------------------- | ---------------------------- | ------------------------------------------------------------------------ | | Duration type
(ISO 8601 parse/format/arithmetic) | ✅ Done | Luxon `Duration` | | Interval/range math
(contains, overlap, union,
intersection, split, set ops) | ✅ Done | Luxon `Interval`,
date-fns `areIntervalsOverlapping` | | DST disambiguation control
on construction _and_ arithmetic | ✅ Done — **differentiator** | None of the others expose
this on arithmetic | | Locale-aware calendar helpers
(weekend, week start/end, day-of-week) | ✅ Done | `@internationalized/date` | | Business-day arithmetic,
clamp/closest, time rounding | ✅ Done | `temporal-kit` | | Interval rounding-out
(boundary count, from-duration) | ✅ Done | Luxon | | Locale calendar metadata
(names, `hasDST`) | ✅ Done | Luxon `Info` | | Overlap-day count, relative
rounding, DST transitions, hours-in-day | ✅ Done | date-fns, `@internationalized/date` | | Field setters, token-pattern
parsing, named machine formats,
calendar-style formatting | ✅ Done | Luxon `.set()`,
`toRFC2822`/`toHTTP`/`toSQL`,
Moment `.calendar()` | | Non-Gregorian calendar systems
(conversion + calendar-aware
interval/duration math) | ✅ Done | `@internationalized/date`'s
`toCalendar` | Status reflects [context/roadmap/tracker.md](https://github.com/burglekitt/gmt/tree/main/context/roadmap/tracker.md) as of this writing. ### Where GMT stands alone Specific, sourced claims — not a repeat of the metrics above. | Claim | The others | | --------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | | Only GMT runs its **entire** suite in CI
under a real `TZ` env var across 10
real-world zones × 2 Node versions
(20 full-suite runs) | Luxon/`@internationalized/date`: no
CI timezone matrix. date-fns: zone
scope unclear. Moment.js: 6 zones,
partial suite only | | Only GMT enforces a mandatory
17-locale test matrix on every
locale-aware function | No CI-level or systematic
locale-matrix testing found
in any of the four | | Only GMT exposes explicit DST
disambiguation control on both
construction _and_ arithmetic | Luxon's docs call this explicitly
undefined; `@internationalized/date`
only covers construction, not arithmetic | | Only GMT is Temporal-native with
zero `Date` usage, enforced by
3 dedicated lint packages | Luxon, date-fns, and Moment.js all
still wrap or depend on `Date` internally | | GMT's effective CI test
executions exceed all four
competitors **combined**
by ~15× | 312,220 vs. 386 + 4,888 + 3,213
+ 11,703 = 20,190 | ## Package Layout The package exports seven top-level namespaces: ```typescript import { Temporal, duration, plain, zoned, unix, utc, regex, } from "@burglekitt/gmt"; ``` - `Temporal`: re-exported from `@js-temporal/polyfill` - `duration`: ISO 8601 duration string parsing, validation, and arithmetic - `plain`: timezone-free helpers - `zoned`: timezone-aware helpers - `unix`: Unix epoch (seconds or milliseconds) helpers - `utc`: UTC instant helpers - `regex`: low-level regex building blocks You can also import subpaths directly: ```typescript import { addDate, getNow, formatRelativeZoned } from "@burglekitt/gmt"; ``` ## Quick Start ### Plain arithmetic and comparisons ```typescript import { addDate, addBusinessDays, subtractBusinessDays, areDatesEqual, diffDateTime, isBeforeDateTime, } from "@burglekitt/gmt"; addDate("2026-01-01", 90, "day"); // "2026-03-32" is impossible, so Temporal normalizes correctly -> "2026-04-01" addBusinessDays("2024-03-15", 1); // "2024-03-18" (skips weekend) subtractBusinessDays("2024-03-18", 1); // "2024-03-15" (skips weekend) diffDateTime("2024-03-17T12:00:00", "2024-03-17T12:30:00", "minute"); // 30 areDatesEqual("2026-03-17", "2026-03-17T09:00:00"); // true isBeforeDateTime("2026-03-17T09:00:00", "2026-03-17T10:00:00"); // true ``` `add*`/`subtract*` accept an optional `overflow` (`"constrain"` (default) | `"reject"`) to control out-of-range results (e.g. adding a month to Jan 31), and `diff*` accept optional `smallestUnit`/`roundingIncrement`/`roundingMode` to round the computed difference: ```typescript import { addDate, diffDate } from "@burglekitt/gmt"; addDate("2024-01-31", { months: 1 }, { overflow: "reject" }); // "" — Feb 31 doesn't exist and overflow: "reject" refuses to clamp it diffDate("2023-01-01", "2023-01-10", "week", { smallestUnit: "week", roundingMode: "halfExpand", }); // 1 ``` `setDate`/`setDateTime`/`setTime`/`setZoned`/`setUnix`/`setUtc` set one or more fields on a value in a single atomic `.with()`-based call — the safe alternative to composing `add*` calls field-by-field, which resolves each field's overflow independently and can silently diverge on multi-field updates: ```typescript import { setDate, setZoned } from "@burglekitt/gmt"; setDate("2024-01-31", { month: 2 }); // "2024-02-29" (constrain, the default, clamps to the last valid day) setZoned( "2024-11-03T01:45:00-05:00[America/New_York]", { minute: 0 }, { disambiguation: "reject", }, ); // "" — offset defaults to "ignore" so disambiguation actually fires on this fall-back overlap ``` `setZoned`/`setUnix`/`setUtc` also accept `disambiguation` and `offset` for DST gap/overlap control — see [DST Disambiguation](../../docs/dst-disambiguation.md). `cycleDate`/`cycleDateTime`/`cycleTime`/`cycleZoned` adjust a single field and **wrap** at that field's own min/max instead of carrying into the next larger field — the datepicker-segment-editing primitive `add*` can't express, since overflowing into the next field is exactly what `add*` is for: ```typescript import { addDate, cycleDate, cycleZoned } from "@burglekitt/gmt"; cycleDate("2024-12-15", "month", 1); // "2024-01-15" — stays in the same year addDate("2024-12-15", { months: 1 }); // "2025-01-15" — addDate correctly overflows into the next year instead cycleZoned("2024-03-10T01:30:00-06:00[America/Chicago]", "hour", 1); // "2024-03-10T03:30:00-05:00[America/Chicago]" — the cycled hour lands in a spring-forward // gap; disambiguation ("compatible" by default) resolves it the same way setZoned does ``` `cycleZoned` also accepts `disambiguation` and `offset` (default `offset: "ignore"`) for the same DST gap/overlap control as `setZoned` — see [DST Disambiguation](../../docs/dst-disambiguation.md). `options.round` on any of the four steps to the next multiple of `amount` rather than rounding to the nearest one, matching `@internationalized/date`'s `CycleOptions.round`. `isWeekend`/`isZonedWeekend` check locale-specific weekend days (via `Intl.Locale`'s `weekInfo`) rather than assuming Saturday/Sunday: ```typescript import { isWeekend, isZonedWeekend } from "@burglekitt/gmt"; isWeekend("2024-02-03", "en-US"); // true (Saturday, en-US weekend is Sat/Sun) isWeekend("2024-02-03", "he-IL"); // true (Saturday is also part of he-IL's Fri/Sat weekend) isZonedWeekend("2024-02-04T10:00:00+02:00[Asia/Jerusalem]", "he-IL"); // false (Sunday isn't part of he-IL's weekend) ``` `isBusinessDay` returns true for fixed ISO Monday–Friday business days (Mon=1 … Fri=5), locale-agnostic and with no holiday calendar. It's the complement to locale-aware `isWeekend` and matches the boundary that `addBusinessDays`/`subtractBusinessDays` use: ```typescript import { isBusinessDay } from "@burglekitt/gmt"; isBusinessDay("2024-02-05"); // true (Monday) isBusinessDay("2024-02-10"); // false (Saturday) ``` `isRelativeDay`/`isThisUnit`/`isPast`/`isFuture` are now-relative predicates — `isRelativeDay` subsumes `isToday`/`isYesterday`/`isTomorrow`, `isThisUnit` subsumes `isThisWeek`/`isThisMonth`/`isThisYear`. They compare against `getToday()`, so they depend on the **system clock and system timeZone**; the zoned variants (`isZonedRelativeDay`, `isZonedThisUnit`, `isZonedPast`, `isZonedFuture`) resolve "today"/"now" in the value's own timeZone instead, for deterministic results regardless of the host machine's timeZone: ```typescript import { isRelativeDay, isThisUnit, isPast, isFuture } from "@burglekitt/gmt"; isRelativeDay("2024-03-15", 0); // true, if today is 2024-03-15 ("isToday") isThisUnit("2024-02-26", "week", "fr-FR"); // locale-aware week boundary — fr-FR weeks start Monday isPast("2024-03-14"); // true, if today is 2024-03-15 (strictly before, not on-or-before) isFuture("2024-03-16"); // true, if today is 2024-03-15 (strictly after, not on-or-before) ``` `nextWeekday`/`previousWeekday` find the next/previous occurrence of a given ISO day of week (1 = Monday … 7 = Sunday, matching `getDayOfWeek`) on or after/before a date, replacing date-fns's sixteen `next*`/`previous*` functions with two parameterized calls. `options.inclusive` (default `false`) controls what happens when the input already falls on the target day — `false` advances/retreats a full week, matching date-fns: ```typescript import { nextWeekday, previousWeekday } from "@burglekitt/gmt"; nextWeekday("2024-03-13", 5); // "2024-03-15" (Wednesday -> next Friday) nextWeekday("2024-03-15", 5); // "2024-03-22" (already a Friday -> advances a full week by default) nextWeekday("2024-03-15", 5, { inclusive: true }); // "2024-03-15" (already a Friday -> returned as-is) previousWeekday("2024-03-13", 5); // "2024-03-08" (Wednesday -> previous Friday) ``` ```typescript import { isZonedRelativeDay, isZonedPast } from "@burglekitt/gmt"; isZonedRelativeDay("2024-03-15T10:00:00-04:00[America/New_York]", 0); // "today" resolved in America/New_York, not the host's system timeZone isZonedPast("2020-01-01T00:00:00Z[UTC]"); // true — compares the exact instant, not just the calendar day ``` `clampDate` restricts a date to a range, and `closestDateTo` finds the nearest candidate by calendar distance: ```typescript import { clampDate, closestDateTo } from "@burglekitt/gmt"; clampDate("2024-02-01", "2024-03-01", "2024-03-31"); // "2024-03-01" closestDateTo("2024-03-15", ["2024-03-01", "2024-03-20", "2024-03-18"]); // "2024-03-18" ``` `getLocaleStartOfWeek`/`getLocaleEndOfWeek` (and their zoned equivalents) compute week boundaries from the locale's first day of week, instead of an ISO-Monday default: ```typescript import { getLocaleStartOfWeek, getLocaleEndOfWeek } from "@burglekitt/gmt"; getLocaleStartOfWeek("2024-02-29", "en-US"); // "2024-02-25" (Sunday, en-US weeks start Sunday) getLocaleStartOfWeek("2024-02-29", "fr-FR"); // "2024-02-26" (Monday, fr-FR weeks start Monday) getLocaleEndOfWeek("2024-02-29", "en-US"); // "2024-03-02" (Saturday) ``` `getLocaleDayOfWeek`/`getLocaleZonedDayOfWeek` return a locale-relative day-of-week index (0 = first day of the locale's week): ```typescript import { getLocaleDayOfWeek, getLocaleZonedDayOfWeek } from "@burglekitt/gmt"; getLocaleDayOfWeek("2024-02-25", "en-US"); // 0 (Sunday = first day of en-US week) getLocaleDayOfWeek("2024-02-26", "fr-FR"); // 0 (Monday = first day of fr-FR week) getLocaleDayOfWeek("2024-02-24", "he-IL"); // 0 (Saturday = first day of he-IL week) getLocaleZonedDayOfWeek("2024-02-25T12:00:00+00:00[UTC]", "en-US"); // 0 ``` `getLocaleEraNames`/`getLocaleMonthNames`/`getLocaleWeekdayNames`/`getLocaleMeridiems` return standalone, locale-aware calendar names with no date value required — the GMT equivalents of Luxon's `Info.eras`/`Info.months`/`Info.weekdays`/`Info.meridiems`: ```typescript import { getLocaleEraNames, getLocaleMonthNames, getLocaleWeekdayNames, getLocaleMeridiems, } from "@burglekitt/gmt"; getLocaleEraNames("en-US"); // ["Before Christ", "Anno Domini"] getLocaleEraNames("ja-JP", "short"); // ["紀元前", "西暦"] getLocaleMonthNames("en-US"); // ["January", "February", ... "December"] getLocaleMonthNames("de-DE", "short"); // ["Jan", "Feb", "Mär", ... "Dez"] getLocaleWeekdayNames("en-US"); // ["Sunday", "Monday", ... "Saturday"] (locale-first-day order) getLocaleWeekdayNames("fr-FR"); // ["lundi", "mardi", ... "dimanche"] getLocaleMeridiems("en-US"); // ["AM", "PM"] getLocaleMeridiems("zh-CN"); // ["上午", "下午"] ``` `getLocaleWeekdayNames` returns names in the locale's first-day order, consistent with `getLocaleDayOfWeek` (index 0 is the locale's first day of the week). All four delegate to the host runtime's `Intl` data, so their output depends on the runtime's ICU build. ### Parsing `parseDateWithPattern`/`parseDateTimeWithPattern`/`parseTimeWithPattern` decode a known, fixed producer format — a CSV column, a legacy API field, or a partially-typed form value — against a caller-supplied token pattern. This is for **decoding**, not display: the pattern hard-codes field order, so `formatDate`/`formatDateToParts` remain the correct choice for locale-correct output. ```typescript import { parseDateWithPattern, parseDateTimeWithPattern, parseTimeWithPattern, } from "@burglekitt/gmt"; parseDateWithPattern("03/15/2024", "MM/dd/yyyy"); // "2024-03-15" parseDateTimeWithPattern("15-Mar-2024 14:30", "dd-MMM-yyyy HH:mm"); // "2024-03-15T14:30:00" parseTimeWithPattern("02:30:45 PM", "hh:mm:ss a"); // "14:30:45" parseDateWithPattern("02/31/2024", "MM/dd/yyyy"); // "" — shape-valid but not a real date; Temporal validates after the regex match ``` Supported tokens include `yyyy`/`MM`/`dd`/`HH`/`mm`/`ss`/`SSS` for fixed-width fields, `M`/`d`/`H`/`h`/`m`/`s` for variable-width, `MMMM`/`MMM`/`EEEE`/`EEE`/`a`/`GGGG`/`GG` for locale-aware names, and `'single quotes'` for literal text. A `locale` parameter (default `"en-US"`) controls name-token matching. Invalid input, no-match, and malformed patterns all return `""`. ### Calendar systems GMT's `CalendarSystem` type (`"gregorian" | "hebrew" | "islamic-civil" | "islamic-tabular" | "islamic-umalqura" | "japanese" | "buddhist" | "taiwan" | "persian" | "indian" | "ethiopic" | "ethiopic-amete-alem" | "coptic"`, extended by later stories) and `convertDateToCalendar` express a date in a non-Gregorian calendar system, built almost entirely on Temporal's native calendar support — no bundled leap-year tables or ported arithmetic, with one deliberate exception (the Ethiopic family, covered below). ```typescript import { convertDateToCalendar } from "@burglekitt/gmt"; convertDateToCalendar("2024-10-03", "hebrew"); // "5785-01-01[u-ca=hebrew]" — Rosh Hashanah 5785 convertDateToCalendar("5785-01-01[u-ca=hebrew]", "gregorian"); // "2024-10-03" — round-trips back convertDateToCalendar("2024-10-03", "islamic-umalqura"); // "1446-03-30[u-ca=islamic-umalqura]" — Saudi Umm al-Qura calendar convertDateToCalendar("invalid", "hebrew"); // "" ``` The output string shape is the key design decision here, and it deliberately **diverges from Temporal's own** `[u-ca=...]` convention. Temporal's `Temporal.PlainDate.prototype.toString()` always keeps the ISO/proleptic-Gregorian year-month-day digits and only tags the calendar (`"2024-10-03[u-ca=hebrew]"` — still literally October 3rd's Gregorian digits). That hides the calendar's own fields behind calendar-aware accessors, which GMT's string-only contract has no place for. GMT's annotated string instead carries the **calendar-native** year/month/day — Hebrew year 5785, not 2024 — so the calendar-system concept is visible directly in the string, not just in an object property. A plain, unannotated ISO string is always treated as (and always produced for) the `"gregorian"` calendar, so every existing GMT function keeps working unchanged. Hebrew years can run 12 or 13 months (7 leap years per 19-year Metonic cycle insert a 13th month, Adar I, before the regular Adar); `convertDateToCalendar` resolves this the same way Temporal does internally, via ordinal month numbers (`1`-`13`) rather than fixed month names, so no month-counting logic lives in GMT itself. Three Islamic (Hijri) calendar variants are supported, and they are **not interchangeable** — each resolves the same Gregorian date to different calendar-native digits: - `"islamic-civil"` — a fixed 30-year leap-year cycle, Friday epoch (`1 AH = 622-07-19`). - `"islamic-tabular"` — the same style of fixed arithmetic cycle, but a Thursday epoch one day earlier (`1 AH = 622-07-18`); maps to Temporal's `"islamic-tbla"` calendar id internally, though GMT's own string annotation always reads `[u-ca=islamic-tabular]`. - `"islamic-umalqura"` — the Saudi civil calendar, based on Umm al-Qura University's own published tables rather than a fixed arithmetic rule. This is **not** approximated by the tabular variant's math — `convertDateToCalendar("2020-02-24", "islamic-umalqura")` returns `"1441-06-30[u-ca=islamic-umalqura]"` while the same input under `"islamic-tabular"` returns `"1441-07-01[u-ca=islamic-tabular]"`, a genuine one-day divergence, not a rounding difference. Five era-based solar calendars round out the set. Unlike Hebrew and the Islamic variants, none of these needed new leap-year logic — each is either Gregorian-shaped with a different year numbering layered on top, or a distinct-but-simple solar calendar, so they were materially less work than Hebrew or Islamic: - `"buddhist"` — Gregorian day/month structure, a fixed `+543` year offset (`convertDateToCalendar("2024-10-03", "buddhist")` → `"2567-10-03[u-ca=buddhist]"`). One continuous era, no reset. - `"taiwan"` — Gregorian day/month structure, year numbering reset at 1912 (the Republic of China's founding): `2024` → `"0113-10-03[u-ca=taiwan]"` (`2024 - 1911`). Dates before 1912 count backward through Temporal's inverse era instead of going negative in the way a plain offset would — `convertDateToCalendar("1911-12-31", "taiwan")` is `"0000-12-31[u-ca=taiwan]"`, not `"-0001-12-31"`. - `"persian"` — a genuinely distinct solar calendar (not Gregorian-derived): own month lengths (6 months of 31 days, 5 of 30, a 29/30-day 12th month) and its own 33-year leap-year cycle (a year is leap when `(25 × year + 11) mod 33 < 8`), verified against `@internationalized/date`'s `PersianCalendar.ts` rather than assumed from the offset-only calendars above. - `"indian"` — the Indian National Calendar (Saka era, epoch 78 CE). Also not offset-only: its leap-year alignment follows the Gregorian rule rather than an independent cycle — the calendar's first month is 31 days in a Gregorian leap year, 30 otherwise, which is why its Saka-year boundary (`convertDateToCalendar("2024-03-20", "indian")` → `"1945-12-30[u-ca=indian]"`, `convertDateToCalendar("2024-03-21", "indian")` → `"1946-01-01[u-ca=indian]"`) doesn't land on a fixed day-of-year every year. - `"japanese"` — era-based: the year resets to `1` at each imperial era change (Meiji, Taishō, Shōwa, Heisei, Reiwa). This is the one calendar where GMT's annotated string carries an era-relative year instead of the calendar's plain native year, and needs its own explanation below. **Why `"japanese"` gets a different string shape.** Every other supported calendar's plain `year` field is exactly what belongs in GMT's annotated string — Hebrew year 5785, Taiwan year 113, and so on are each already the single number that identifies the year. Japanese is the exception: Temporal's `.year` for the `"japanese"` calendar stays **proleptic** across era changes (it doesn't reset — `1912-07-30`, the first day of Taishō, still reports `.year === 1912`, not `1`), because Temporal's `.year` is designed to be a stable sort key, not a display value. Using it directly would silently contradict the calendar's entire reason for existing. So `convertDateToCalendar` uses Temporal's `.eraYear` (the field that _does_ reset) paired with the era name, tagged onto the annotation as `;era=`: ```typescript convertDateToCalendar("2024-10-03", "japanese"); // "0006-10-03[u-ca=japanese;era=reiwa]" — year 6 of the Reiwa era, not the proleptic 2024 convertDateToCalendar("1912-07-30", "japanese"); // "0001-07-30[u-ca=japanese;era=taisho]" — the first day of Taishō reads year 1 convertDateToCalendar("0001-07-30[u-ca=japanese;era=taisho]", "gregorian"); // "1912-07-30" — round-trips back through the era + eraYear pair ``` `@internationalized/date` documents pre-Meiji (before 1868-10-23) dates as unsupported for its Japanese calendar. GMT does not replicate that restriction: since `convertDateToCalendar` is built entirely on Temporal's own calendar support rather than a ported implementation, and Temporal resolves those dates correctly under a synthetic `"japanese"` era (with an ISO-aligned `eraYear`), rejecting them would mean writing new validation solely to reproduce another library's gap rather than an actual GMT limitation. `convertDateToCalendar("1800-01-01", "japanese")` returns `"1800-01-01[u-ca=japanese;era=japanese]"` rather than `""`. Three Ethiopic-family calendars round out the set, all sharing one 13-month structure (12 months of 30 days, plus a short Pagume/Nasie 13th month of 5 days, or 6 in a leap year) but differing in epoch: - `"ethiopic"` — the modern Ethiopian calendar, era-based like `"japanese"`: it resets to the Amete Mihret ("Year of Mercy"/Incarnation) era at its own epoch (~AD 8), so `convertDateToCalendar("2024-10-03", "ethiopic")` returns `"2017-01-23[u-ca=ethiopic;era=ethiopic]"` — year 2017, not a 5-digit proleptic number. Dates before that epoch resolve under the Amete Alem ("Year of the World") era instead: `convertDateToCalendar("0001-01-01", "ethiopic")` → `"5493-05-08[u-ca=ethiopic;era=ethioaa]"`. - `"ethiopic-amete-alem"` — the same calendar, but always counted continuously from the Amete Alem epoch (~5493 BCE), never resetting: `convertDateToCalendar("2024-10-03", "ethiopic-amete-alem")` → `"7517-01-23[u-ca=ethiopic-amete-alem]"`. - `"coptic"` — the Coptic Orthodox calendar: same 13-month structure, its own epoch (the Diocletian/Martyrs era, AD 284): `convertDateToCalendar("2024-10-03", "coptic")` → `"1741-01-23[u-ca=coptic]"`. **Why this family isn't built on Temporal's native `"ethiopic"`/`"coptic"` calendar ids, unlike every other calendar above.** `@js-temporal/polyfill`'s implementation of these two calendars resolves year/era by formatting the date through `Intl.DateTimeFormat` and matching the result against a hardcoded era-name table — unlike calendars with a fixed year-offset from ISO (Buddhist, Taiwan, and Ethiopic Amete Alem, which the polyfill computes with pure arithmetic and never touches `Intl` for). CLDR's era-name output for these two calendars changed between ICU versions: under ICU ≥ 78 (the version Node 22 and 24 both bundle — this is an ICU-version boundary, not a Node-major one), every read _or_ write of Temporal's `"ethiopic"`/`"coptic"` calendar ids throws a `RangeError` (`Era am (ISO year …) was not matched by any era`) — confirmed directly, not a hypothetical. `"ethiopic-amete-alem"` (Temporal's `"ethioaa"` id) is unaffected, since it has no era at all and is resolved with pure arithmetic. GMT routes around the bug rather than inheriting it: month/day are identical across all three calendars (they share one annual cycle), so `convertDateToCalendar` reads/writes them via the safe `"ethioaa"` calendar and computes each calendar's own displayed year (+ era, for `"ethiopic"`) with GMT-owned arithmetic — ported from the same `EthiopicHelper`/`CopticHelper` epoch constants `@js-temporal/polyfill` itself uses internally, just evaluated in GMT's code instead of through the ICU-dependent path. See `internal/ethiopicFamilyCalendar.ts` for the implementation. #### Calendar-aware interval and duration arithmetic `convertDateToCalendar`'s output feeds directly back into `addDate`/`subtractDate`/`diffDate`/`diffDateAsDuration` and every `Date`-suffixed `plain/interval/*` function (`intervalContainsDate`, `intervalCountDate`, `splitIntervalByUnitDate`, and the rest) — calendar-unit arithmetic ("add 1 month") resolves in the value's own calendar rather than being rejected or silently treated as Gregorian: ```typescript addDate("5784-06-15[u-ca=hebrew]", { months: 1 }); // "5784-07-15[u-ca=hebrew]" — Adar I (a leap-only 30-day month) -> Adar intervalCountDate("5784-01-01[u-ca=hebrew]", "5785-01-01[u-ca=hebrew]", "month"); // 13 — a Hebrew leap year crosses 13 month boundaries, not 12 (ISO's answer for the same span) diffDate("5784-06-15[u-ca=hebrew]", "5784-07-15[u-ca=hebrew]", "months"); // 1 — measured in the shared calendar when both endpoints carry the same tag ``` `utc/` and `unix/` reject a `[u-ca=...]` calendar annotation outright, and `duration/`'s `relativeTo` option accepts GMT's calendar-annotated string (not Temporal's own differently-shaped `[u-ca=...]` convention) when a calendar-aware anchor is needed: ```typescript durationAs("P1Y", "days", { relativeTo: "5784-06-15[u-ca=hebrew]" }); // 385 — a Hebrew leap year, not the 366 a Gregorian P1Y would total ``` `zoned/` has its own calendar-annotated grammar as of E7 (issue #152) — see "Calendar-aware zoned datetimes" below. Interval functions that only compare or diff absolute instants (`intervalContainsDate`, `intervalsOverlapDate`, `intervalAbutsDate`, `intervalEngulfsDate`, `isValidDateInterval`, `intervalOverlappingDaysDate`) accept endpoints tagged with *different* calendars, since ordering and day-counting don't depend on which calendar a date is expressed in. Functions that return a date *value* (`intervalUnionDate`, `intervalIntersectionDate`, `intervalDifferenceDate`, `intervalXorDate`, `intervalXorAllDate`, `mergeIntervalsDate`, `intervalDivideEquallyDate`, `intervalSplitAtDate`) require every argument to share one calendar and return their sentinel (`null`/`[]`) on a mismatch, since there's no principled way to pick which calendar the output should be expressed in. See `context/roadmap/issues/E.md`'s "E5 outcome" section for the full per-function audit, including the negatives ("no change needed, verified why") this scope boundary implies — `*DateTime`/`*Time` variants, `unix/`, and `utc/` were all confirmed unaffected rather than assumed to be. #### Calendar-aware zoned datetimes A calendar-annotated `ZonedDateTime` string adds a time, a UTC offset and an IANA zone to the plain grammar above: ``` T