Introduction
A lightweight datetime utility library built on the Temporal API
What is tiempo?
tiempo is a lightweight utility library for timezone conversions, formatting, and date math—built on the modern Temporal API for precision you can trust.
JavaScript's Date was modeled after a Java class deprecated 25+ years ago. The Temporal API is its modern replacement—tiempo makes it accessible with a familiar, date-fns-style API.
Key Features
- Any Timezone, Anywhere - Date only works in UTC or device-local time. Temporal supports 400+ IANA timezones natively
- Nanosecond Precision - Beyond milliseconds, for scientific computing, financial systems, and high-frequency operations
- DST-Safe Arithmetic - Adding days means calendar days, not 24-hour periods. No more off-by-one-hour bugs
- Immutable by Design - No side effects, no surprises, no debugging mysteries
- Distinct Types - Separates
Instant(timestamp),ZonedDateTime(timezone-aware), andPlainDate(calendar date) - Type-Safe - Autocomplete for 400+ timezones, invalid configurations caught at compile time
Quick Example
import { toZonedTime, format, today, addDays, isBefore } from '@gobrand/tiempo';
// Convert UTC to a timezone
const nyTime = toZonedTime(new Date(), 'America/New_York');
// Format with full control
const formatted = format(nyTime, 'EEEE, MMMM d, yyyy h:mm a');
// → "Thursday, January 23, 2026 2:30 PM"
// Today's date in any timezone
const tokyoToday = today('Asia/Tokyo');
// Date arithmetic
const nextWeek = addDays(nyTime, 7);
// Comparisons
const isUpcoming = isBefore(nyTime, nextWeek); // true