微信扫一扫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 |
|----------|-------------|-----------|
| toInstant() | Convert a timeline representation to a Temporal Instant | details |
| toZonedTime() | Convert to a timezone-aware ZonedDateTime | details |
| toPlainDate() | Parse a plain date or extract calendar date from a datetime | details |
| toPlainTime() | Parse a plain time or extract wall-clock time from a datetime | 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 |
| addQuarters() | Add quarters 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 |
| subQuarters() | Subtract quarters 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 boundary of the week (Monday) | details |
| endOfWeek() | Get the last boundary of the week (Sunday) | details |
| startOfMonth() | Get the first boundary of the month | details |
| endOfMonth() | Get the last boundary of the month | details |
| startOfQuarter() | Get the first moment of the quarter | details |
| endOfQuarter() | Get the last moment of the quarter | details |
| startOfYear() | Get the first boundary of the year | details |
| endOfYear() | Get the last boundary 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 |
| isSameQuarter() | Check if two datetimes are in the same calendar quarter | 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 |
| differenceInQuarters() | Calculate the difference between two dates in quarters | 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 |
| eachQuarterOfInterval() | Get all quarters 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 |
|----------|-------------|-----------|
| getQuarter() | Get the quarter (1-4) that a datetime falls in | details |
| 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';