Skip to Content
UtilsDate

Date utils

import { formatDate, formatRelativeTime, addDays } from '@gg-software/utils';

Formatters use Intl.DateTimeFormat / Intl.RelativeTimeFormat; pass locale in the options to override the runtime default.

formatDate

Defaults to a medium date; any Intl.DateTimeFormatOptions override that.

formatDate(new Date()); // "Jul 2, 2026"
formatDate(new Date(), { locale: 'cs-CZ' }); // "2. 7. 2026"
formatDate(new Date(), { dateStyle: 'short', timeStyle: 'short' }); // "7/2/26, 3:04 PM"

formatDateRange

Start–end range, compact (shared parts collapse).

formatDateRange(new Date('2026-07-01'), new Date('2026-07-14')); // "Jul 1 – 14, 2026"
formatDateRange(start, end, { locale: 'cs-CZ' }); // "1. – 14. 7. 2026"

formatRelativeTime

“3 hours ago” / “tomorrow” — picks the largest sensible unit, localized.

formatRelativeTime(threeHoursAgo); // "3 hours ago"
formatRelativeTime(inTwoDays); // "in 2 days"
formatRelativeTime(date, { locale: 'cs-CZ' }); // "před 3 hodinami"
formatRelativeTime(date, { now: referenceDate }); // compare against a fixed point

parseDate

Safe parsing — returns null instead of an Invalid Date.

parseDate('2026-07-02'); // Date
parseDate(1767225600000); // Date (timestamp)
parseDate('nonsense'); // null
parseDate(null); // null

addDays / addMonths

Date arithmetic; both return a new Date. addMonths clamps when the target month is shorter.

addDays(new Date('2026-07-02'), 7); // 2026-07-09
addDays(new Date('2026-07-02'), -2); // 2026-06-30
addMonths(new Date('2026-01-31'), 1); // 2026-02-28 (clamped)

isToday / isSameDay

Calendar-day comparisons in local time.

isSameDay(new Date('2026-07-02T08:00'), new Date('2026-07-02T23:59')); // true
isToday(new Date()); // true
NumberArray