Skip to content
@northguild/gmt

Parsing Date and Time

GMT’s parse functions accept ISO 8601 strings and common wire formats, returning plain or zoned components. They never throw — invalid input yields an empty string or null.

Mistakes

Section titled “Mistakes”
HIGH

Not handling null on invalid input

parseRfc2822, parseHttp, and parseSql return null for invalid input, not an empty string. Checking for falsy is not enough — null and an empty string are different sentinels with different meanings.

Wrong

const result = parseRfc2822(invalidInput);
if (!result) { /* catches null and "" */ } // ambiguous

Right

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

const result = parseRfc2822(invalidInput);
if (result === null) {
// specifically invalid Rfc2822
}
MEDIUM

Using string manipulation instead of parse functions

Splitting a date string on '-' and indexing the parts works for ISO 8601 today, but it breaks the moment your input includes a calendar annotation, a different separator, or fractional seconds.

Wrong

const [y, m, d] = dateStr.split("-"); // fragile — breaks on annotations or edge formats

Right

import { parseYearFromDate, parseMonthFromDate, parseDayFromDate } from "@northguild/gmt";

const y = parseYearFromDate(dateStr);
const m = parseMonthFromDate(dateStr);
const d = parseDayFromDate(dateStr);
MEDIUM

Assuming month is 1-indexed in arithmetic

Temporal.PlainMonthDay uses 1-indexed months, but parseMonthFromDate returns 1-12. Adding or subtracting months without normalizing through a date-aware function can produce invalid month values.

Wrong

const m = parseMonthFromDate("2024-12-15"); // 12
const next = m + 1; // 13 — not a valid month

Right

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

addMonths("2024-12-15", 1); // "2025-01-15" — handles overflow
MEDIUM

Confusing getWeekOfMonth with parseWeekFromDate

getWeekOfMonth tells you which week-of-month a date falls in (1-6). parseWeekFromDate returns the ISO week number (1-53). They answer different questions and produce different numbers for the same input.

Wrong

const wom = getWeekOfMonth("2024-01-31"); // 5
// used as if it were an ISO week number

Right

import { parseWeekFromDate, parseYearFromDate } from "@northguild/gmt";

const isoWeek = parseWeekFromDate("2024-01-31"); // 5
const weekYear = parseYearFromDate("2024-01-31"); // 2024 — the week-year, not the calendar year
MEDIUM

Week number without week-year is a bug in waiting

'Wait until week 35' is ambiguous without a week-year. ISO week 35 of 2024 and week 35 of 2025 are 52 weeks apart. Always pair the week number with its week-year.

Wrong

const week = parseWeekFromDate(startDate); // 35
// wait until week 35 — but which year?

Right

import { parseWeekFromDate, parseYearFromDate } from "@northguild/gmt";

const week = parseWeekFromDate(startDate);
const weekYear = parseYearFromDate(startDate);
// wait until week <week> of <weekYear>
MEDIUM

Checking for null on parseRfc2822/parseHttp/parseSql/parseRfc3339

These functions return null for invalid input. Checking for a falsy return masks the difference between invalid (null) and valid-but-empty (an empty string). Check for null explicitly.

Wrong

const r = parseRfc3339(input);
if (!r) { /* treats null and "" identically */ }

Right

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

const r = parseRfc3339(input);
if (r === null) {
// explicitly invalid input
}

See also

Section titled “See also”