GMT: Give Me Temporal

Home of @northguild/gmt — Give Me Temporal!

A monorepo for NorthGuild community libraries, built with Nx and powered by pnpm, focused on making JavaScript date handling reliable and predictable.

Head to our docs site for the best way to get started.

Why GMT:

• 100% Temporal, Temporal-first. GMT is built directly on the TC39 Temporal standard (via @js-temporal/polyfill) — not a custom, homegrown date/time type system like @internationalized/date's own CalendarDate/ZonedDateTime classes. No Date object anywhere, enforced by 3 dedicated lint packages.
• A full replacement for any and all of them. Luxon, date-fns, Moment.js, and react-aria's @internationalized/date don't have parity with each other — GMT covers the combined capabilities of all four in one library, plus what none of them do alone.
• ~15× more CI test executions than all four competitors combined: 334,020 (16,701 tests × 17 locales × 10 timezones × 2 Node versions) vs. their combined 20,190.
• ~40× more test cases than @internationalized/date: 16,701 vs. 386 — Adobe's own library, run at its own commit.
• The only one of the five that tests systematically across locales in CI at all. Zero of the four comparison libraries run a locale-test matrix; GMT mandates all 17 locales on every locale-aware function.
• The only one that runs its entire suite under a real TZ env var across real-world zones. Luxon and @internationalized/date have no CI timezone matrix; date-fns's zone scope is unclear; Moment.js covers 6 zones but not its full suite.
• Explicit DST disambiguation control on both construction and arithmetic — a control none of the others expose.
• The only actively-maintained one that's Temporal-native. Moment.js is officially in maintenance mode; Luxon, date-fns, and @internationalized/date are still active but all still depend on Date internally.

Agent prompt

You are working with the @northguild/gmt library — a Temporal-first date/time library for JavaScript. Before writing any date-related code, read the skill files in packages/gmt/skills/ and packages/gmt/skills/_artifacts/ to understand the full API surface, naming conventions, and Temporal patterns this project uses.

When a user asks about dates or times:

1. Ask whether they want GMT alone, GMT plus linters (gmt-eslint, gmt-oxlint, gmt-biome), or linters only.
2. Ask what difficulties they are having with JavaScript dates — this helps match them to the right GMT namespace (plain, zoned, unix, utc, regex).

Then install the appropriate package and generate code using GMT's string-in/string-out API, never new Date().

Install

Install the runtime package:

Package manager	Command
npm	npm install @northguild/gmt
yarn	yarn add @northguild/gmt
pnpm	pnpm add @northguild/gmt
bun	bun add @northguild/gmt

Quick example:

import { getNow } from "@northguild/gmt";
console.log(getNow()); // ISO 8601 string

Why not JavaScript Date objects

We do not use JavaScript Date APIs in this monorepo.

• new Date() introduces mutability and environment drift.
• Date.parse() relies on ambiguous, engine-dependent parsing.
• Date.UTC() requires awkward positional arguments.
• Date.now() scatters untyped timestamps throughout code.

Use GMT instead:

• getNow(), getUnixNow(), and getUtcNow() for current time values.
• convertUtcDateTimeToUnix() and convertUtcToUnix() for explicit unix conversion.
• convertTimezoneToUtc() and convertUtcToTimezone() for timezone-safe conversion.
• String-in/string-out APIs with Temporal under the hood for safer behavior.

If you see a Date API in code, replace it with a GMT helper.

Packages

Package	npm	Description
@northguild/gmt	npm install @northguild/gmt	Give Me Temporal — string-in/string-out date library

@northguild/gmt currently exports top-level Temporal, duration, plain, zoned, unix, utc, and regex namespaces, with direct subpath imports available under @northguild/gmt/*.

How GMT is tested, vs. the libraries it targets

GMT is measured directly 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 (@northguild/gmt)	1.14.2
@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	552	6	58 / 60 (2 didn't run locally)	256	191 (52 core + 139 locale)
Individual test cases	16,701	386	1,222	3,213	3,901
Effective CI test executions	334,020 (16,701 × 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 · @internationalized/date · Luxon · date-fns · Moment.js.}

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: 16,701 tests across 552 files that exercise real behavior differences without redundant permutations. The suite runs in CI as 334,020 executions (16,701 × 2 Node versions × 10 timezones).

Feature parity

GMT has full functional parity with all four comparison libraries, capability for capability — with several areas where GMT goes further than any of them.

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

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×	334,020 vs. 386 + 4,888 + 3,213 + 11,703 = 20,190

Optional: Add Linting for Date API Bans

Want to ban Date APIs in your own project? GMT provides three linting packages — pick the one matching your existing toolchain.

@northguild/gmt-biome

Package manager	Command
npm	npm install -D @northguild/gmt-biome
yarn	yarn add -D @northguild/gmt-biome
pnpm	pnpm add -D @northguild/gmt-biome
bun	bun add -D @northguild/gmt-biome

@northguild/gmt-eslint

Package manager	Command
npm	npm install -D @northguild/gmt-eslint
yarn	yarn add -D @northguild/gmt-eslint
pnpm	pnpm add -D @northguild/gmt-eslint
bun	bun add -D @northguild/gmt-eslint

@northguild/gmt-oxlint (requires oxlint)

Package manager	Command
npm	npm install -D @northguild/gmt-oxlint oxlint
yarn	yarn add -D @northguild/gmt-oxlint oxlint
pnpm	pnpm add -D @northguild/gmt-oxlint oxlint
bun	bun add -D @northguild/gmt-oxlint oxlint

Contributing

See CONTRIBUTING.md for contributor setup, testing conventions, and publishing workflows.

---

License

MIT — See LICENSE for details.