Skip to content
@northguild/gmt

Getting the Current Time

  • The core functions, which every industry uses.

getNow, getToday, and their zoned/UTC/Unix siblings are the entry point for every other operation. These mistakes cover the ways reaching for them goes wrong.

Mistakes

Section titled “Mistakes”
CRITICAL

Using Date.now() instead of Temporal

Date.now() returns epoch milliseconds. GMT functions return ISO strings. They are not interchangeable — 1000× errors are the common result.

Wrong

const ts = Date.now(); // 1710504645000 — milliseconds, but easy to mistake for seconds

Right

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


getNow(); // "2024-03-15T14:30:45.123456789" — ISO 8601 string, no unit confusion
HIGH

Using new Date() for current time

new Date() produces a mutable Date object. GMT returns immutable strings. Mixing the two families forces constant round-tripping and hides timezone bugs.

Wrong

const now = new Date(); // mutable Date object — implicit system timezone

Right

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


getNow(); // "2024-03-15T14:30:45.123456789" — immutable string
MEDIUM

Not handling empty string on error

GMT returns an empty string for invalid input rather than throwing. Treating a falsy return as 'not yet loaded' or skipping the branch silently is a bug.

Wrong

const now = getNow?.(); // if the call returns "", your check may treat it as undefined

Right

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


const now = getNow(); // "" on failure — check explicitly:
if (now === "") {
// handle failure
}
MEDIUM

Looking for value-taking get* functions here

getNow and getToday take no arguments. TypeScript rejects a timezone or format string, and at runtime it is silently ignored — you get the system timezone's time, not the zone you named. The zoned and UTC variants live in their own namespaces.

Wrong

getNow("America/New_York"); // type error; at runtime the argument is ignored — system timezone

Right

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


getZonedNow("America/New_York"); // "2024-03-15T10:30:45.123-04:00[America/New_York]" — zoned variant
MEDIUM

Bucketing by week number without its week-year

A week number (1-53) is not unique without the week-year. Week 1 of 2024 and week 1 of 2025 are different weeks, but the number alone does not tell you which.

Wrong

const week = parseWeekFromDate("2024-01-01"); // 1 — but which year's week 1?

Right

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


getIsoWeekDate("2024-01-01"); // { year: 2024, week: 1, weekday: 1 }
getIsoWeekDate("2024-12-30"); // { year: 2025, week: 1, weekday: 1 } — the week-year, not the calendar year
// bucket by year and week together

See also

Section titled “See also”