tiempo

name	tiempo
description	Use when working with dates, times, timezones, or datetime conversions in TypeScript/JavaScript. Provides guidance on using the tiempo library for timezone-safe datetime handling with the Temporal API.
metadata	{"author":"go-brand"}

tiempo - Timezone-Safe Datetime Handling

Lightweight utility library for timezone conversions built on the Temporal API.

npm install @gobrand/tiempo

Best Practices

• Always use explicit timezones - Never rely on implicit timezone behavior. details
• Don't use JavaScript Date - Use tiempo instead of Date for timezone work. details
• Store UTC, display local - Backend stores UTC, frontend converts for display. details

---

Conversion

Function	Description	Reference
toZonedTime()	Convert to a timezone-aware ZonedDateTime	details
toPlainTime()	Parse a plain time or extract wall-clock time from a datetime	details
toPlainDate()	Parse a plain date or extract calendar date from a datetime	details
toUtc()	Convert to a UTC Instant	details
toIso()	Convert to an ISO 8601 string	details
toIso9075()	Convert to ISO 9075 (SQL) format string	details
toDate()	Convert to a JavaScript Date object	details

Current Time

Function	Description	Reference
now()	Get the current date and time as a ZonedDateTime	details
today()	Get today's date as a PlainDate	details

Formatting

Function	Description	Reference
format()	Format a datetime using date-fns-like format tokens	details
formatPlainDate()	Format a PlainDate using date-fns-like format tokens	details
simpleFormat()	Human-friendly date/time formatting with explicit control over what to display	details
intlFormatDistance()	Format the distance between dates as human-readable, internationalized strings	details

Arithmetic

Function	Description	Reference
addYears()	Add years to a datetime	details
addMonths()	Add months to a datetime	details
addWeeks()	Add weeks to a datetime	details
addDays()	Add days to a datetime (DST-safe)	details
addHours()	Add hours to a datetime	details
addMinutes()	Add minutes to a datetime	details
addSeconds()	Add seconds to a datetime	details
addMilliseconds()	Add milliseconds to a datetime	details
addMicroseconds()	Add microseconds to a datetime	details
addNanoseconds()	Add nanoseconds to a datetime	details
subYears()	Subtract years from a datetime

Boundaries

Function	Description	Reference
startOfDay()	Get the first moment of the day	details
endOfDay()	Get the last moment of the day	details
startOfWeek()	Get the first moment of the week (Monday)	details
endOfWeek()	Get the last moment of the week (Sunday)	details
startOfMonth()	Get the first moment of the month	details
endOfMonth()	Get the last moment of the month	details
startOfYear()	Get the first moment of the year	details
endOfYear()	Get the last moment of the year	details

Comparison

Function	Description	Reference
isBefore()	Check if one datetime is before another	details
isAfter()	Check if one datetime is after another	details
isWithinInterval()	Check if a datetime falls within an interval	details
isFuture()	Check if a datetime is in the future	details
isPast()	Check if a datetime is in the past	details
isSameDay()	Check if two datetimes are on the same calendar day	details
isSameWeek()	Check if two datetimes are in the same ISO week	details
isSameMonth()	Check if two datetimes are in the same calendar month	details
isSameYear()	Check if two datetimes are in the same calendar year	details
isSameHour()	Check if two datetimes are in the same hour	details

Difference

Function	Description	Reference
differenceInYears()	Calculate the difference between two dates in years	details
differenceInMonths()	Calculate the difference between two dates in months	details
differenceInWeeks()	Calculate the difference between two dates in weeks	details
differenceInDays()	Calculate the difference between two dates in days	details
differenceInHours()	Calculate the difference between two dates in hours	details
differenceInMinutes()	Calculate the difference between two dates in minutes	details
differenceInSeconds()	Calculate the difference between two dates in seconds	details
differenceInMilliseconds()	Calculate the difference between two datetimes in milliseconds	details
differenceInMicroseconds()	Calculate the difference between two datetimes in microseconds	details

Intervals

Function	Description	Reference
eachYearOfInterval()	Get all years in an interval as ZonedDateTime array	details
eachMonthOfInterval()	Get all months in an interval as ZonedDateTime array	details
eachWeekOfInterval()	Get all weeks (ISO Monday start) in an interval as ZonedDateTime array	details
eachDayOfInterval()	Get all days in an interval as ZonedDateTime array	details
eachHourOfInterval()	Get all hours in an interval as ZonedDateTime array	details
eachMinuteOfInterval()	Get all minutes in an interval as ZonedDateTime array	details

Utilities

Function	Description	Reference
browserTimezone()	Get the browser/device timezone	details
roundToNearestHour()	Round a datetime to the nearest hour boundary	details
roundToNearestMinute()	Round a datetime to the nearest minute boundary	details
roundToNearestSecond()	Round a datetime to the nearest second boundary	details

Types

import type { Timezone, IANATimezone } from '@gobrand/tiempo';

// Timezone: accepts IANA timezones + "UTC"
const tz: Timezone = 'America/New_York';  // Autocomplete for 400+ timezones

// IANATimezone: strictly IANA identifiers (excludes "UTC")
const iana: IANATimezone = 'Europe/London';

---

Converted and distributed by TomeVault — claim your Tome and manage your conversions.