Skip to content
@northguild/gmt

Getting the Current Time

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" — 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" — 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. Passing a timezone or format string throws — the zoned and UTC variants live in their own namespaces.

Wrong

getNow("America/New_York"); // ERROR: getNow takes no arguments

Right

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

getZonedNow("America/New_York"); // "2024-03-15T10:30:45" — 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 { parseWeekFromDate, parseYearFromDate } from "@northguild/gmt";

const year = parseYearFromDate("2024-01-01"); // 2024
const week = parseWeekFromDate("2024-01-01"); // 1
// week 1 of 2024 is unambiguous

See also

Section titled “See also”