tomevault-io 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';
Converted and distributed by TomeVault — claim your Tome and manage your conversions.