Skip to content
@northguild/gmt

Type Conversion

  • The core functions, which every industry uses.

GMT provides conversion functions between plain, zoned, UTC, Unix, and calendar types. The mistakes here cover unit mismatches, annotation handling, and calendar semantics.

Mistakes

Section titled “Mistakes”
HIGH

Using Date.getTime() for conversion

Date.getTime() returns epoch milliseconds whatever the consumer expects. Handing that number to an API that expects Unix seconds introduces a 1000× unit error. GMT's conversions name the unit: milliseconds by default, seconds when you pass { epochUnit: 'seconds' }.

Wrong

const ms = new Date("2024-03-15").getTime(); // 1710460800000 — milliseconds
const unix = ms; // used as seconds — 1000× too large

Right

import { convertUtcToUnix } from "@northguild/gmt/utc";


convertUtcToUnix("2024-03-15T00:00:00Z"); // 1710460800000 — milliseconds (the default)
convertUtcToUnix("2024-03-15T00:00:00Z", { epochUnit: "seconds" }); // 1710460800 — seconds, named
HIGH

Mixing epoch seconds and milliseconds

getUnixNow() returns milliseconds; getUnixNow({ epochUnit: 'seconds' }) returns seconds. Passing seconds to a function expecting milliseconds (or vice versa) produces timestamps that are 1000× off.

Wrong

const ts = getUnixNow({ epochUnit: "seconds" }); // 1710504645 — seconds
const asMs = ts * 1000; // manual conversion — error-prone

Right

import { getUnixNow } from "@northguild/gmt/unix";


getUnixNow(); // 1710504645000 — milliseconds (the default)
getUnixNow({ epochUnit: "seconds" }); // 1710504645 — seconds
// ask for the unit the consumer expects
MEDIUM

Not handling conversion errors

Conversion functions return a sentinel for invalid input rather than throwing — an empty string from a function that returns a string, null from one that returns a number, such as convertUtcToUnix. A failed conversion is silent — check the result.

Wrong

const result = convertUtcToUnix(badInput); // null

Right

import { convertUtcToUnix } from "@northguild/gmt/utc";


const result = convertUtcToUnix(input);
if (result === null) {
// input was invalid
}
MEDIUM

Reading a calendar year out of the string

convertDateToCalendar and convertZonedToCalendar write the RFC 9557 form: ISO digits, then a [u-ca=...] annotation. The digits are the ISO date in every calendar, so slicing the string gives the ISO year, never the Hebrew year or the Japanese era year. Read calendar fields from Temporal.

Wrong

const jy = convertDateToCalendar("2024-03-15", "japanese").slice(0, 4); // "2024" — the ISO year, not the era year

Right

import { convertDateToCalendar, Temporal } from "@northguild/gmt";


const jp = convertDateToCalendar("2024-03-15", "japanese"); // "2024-03-15[u-ca=japanese]"
Temporal.PlainDate.from(jp).eraYear; // 6 — Reiwa 6
MEDIUM

Using the calendar ids from before 1.16.0

GMT's calendar ids are the canonical BCP 47 / Temporal ids. gregorian, taiwan and islamic-tabular are not calendar ids and return the sentinel; use iso8601 (or gregory), roc and islamic-tbla. An alias Temporal accepts, such as ethiopic-amete-alem, is canonicalized to ethioaa.

Wrong

convertDateToCalendar("2024-10-03", "taiwan"); // "" — not a calendar id

Right

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


convertDateToCalendar("2024-10-03", "roc"); // "2024-10-03[u-ca=roc]"
convertDateToCalendar("2024-10-03[u-ca=roc]", "iso8601"); // "2024-10-03"

See also

Section titled “See also”