Application Integration

The core functions, which every industry uses.

Use these patterns when gmt meets application code outside the date/time layer itself: cache keys, URL params, table sort keys, persisted state.

Stable cache keys

Cache keys should depend on canonical representations — ISO 8601 strings or normalized epoch numbers — never on Date objects or fuzzy strings:

// Good — canonical shapes, stable across environments
["events", { start: "2024-02-29", end: "2024-03-01" }];
["session", { at: 1710504645 }]; // epoch seconds, canonical unit

Validate at boundaries

Validate timezone params before using them as a key or persisting them:

import { isValidTimeZone } from "@northguild/gmt/zoned";

if (!isValidTimeZone(tzParam)) throw new Error("Invalid timezone");

Do the same for a UTC timestamp from a request:

import { isValidUtcTimestamp } from "@northguild/gmt";

if (!isValidUtcTimestamp(body.createdAt)) throw new Error("Invalid timestamp");

It accepts only the plain RFC 3339 spelling, such as 2026-10-06T12:00:00Z, with an optional fraction. See UTC timestamps for other readers.

For Unix epoch times, pick one canonical unit (milliseconds recommended) and stick to it. Convert explicitly when needed with convertUtcToUnix / convertUnixToUtc, which use milliseconds unless you pass { epochUnit: "seconds" }.

Routers

When working with routers (Next.js, React Router, etc.), validate and canonicalize date params before use in loaders or components. A "2024-3-5" param is not the same key as "2024-03-05" — canonicalize with the parsing/validation layer first.

Table libraries

For table libraries (TanStack Table, etc.), use ISO strings for sort keys to ensure consistent ordering across environments. String comparison of ISO 8601 sorts correctly; Date object comparison does not.

The principle

Reiterate gmt’s strict I/O at every boundary: public APIs accept explicit shapes only (ISO 8601 strings, IANA timezone ids, epoch numbers). Keep canonicalized representations at boundaries to ensure cache stability and reproducible behavior across environments.