Application Integration

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:

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

For Unix epoch times, pick one canonical unit (milliseconds recommended) and stick to it. Convert explicitly when needed with convertUtcToUnixMs / convertUnixMsToUtc.

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.