- 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.
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 | details |
subMonths() | Subtract months from a datetime | details |
subWeeks() | Subtract weeks from a datetime | details |
subDays() | Subtract days from a datetime | details |
subHours() | Subtract hours from a datetime | details |
subMinutes() | Subtract minutes from a datetime | details |
subSeconds() | Subtract seconds from a datetime | details |
subMilliseconds() | Subtract milliseconds from a datetime | details |
subMicroseconds() | Subtract microseconds from a datetime | details |
subNanoseconds() | Subtract nanoseconds from a datetime | details |
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 |
isSameMinute() | Check if two datetimes are in the same minute | details |
isSameSecond() | Check if two datetimes are in the same second | details |
isSameMillisecond() | Check if two datetimes are in the same millisecond | details |
isSameMicrosecond() | Check if two datetimes are in the same microsecond | details |
isSameNanosecond() | Check if two datetimes are in the same nanosecond | details |
isPlainDateBefore() | Check if a PlainDate is before another PlainDate | details |
isPlainDateAfter() | Check if a PlainDate is after another PlainDate | details |
isPlainDateEqual() | Check if two PlainDates are equal | details |
isPlainTimeBefore() | Check if a PlainTime is before another PlainTime | details |
isPlainTimeAfter() | Check if a PlainTime is after another PlainTime | details |
isPlainTimeEqual() | Check if two PlainTimes are equal | 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 |
differenceInNanoseconds() | Calculate the difference between two datetimes in nanoseconds | 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';
