# tiempo

> A lightweight datetime utility library for timezone conversions, formatting, and date math built on the Temporal API.

tiempo provides a familiar date-fns-style API while leveraging the modern Temporal API for precision you can trust. It supports 400+ IANA timezones, nanosecond precision, DST-safe arithmetic, and immutable operations.

## Docs

- [Introduction](https://tiempo.gobrand.app/docs): Overview of tiempo and key features
- [Installation](https://tiempo.gobrand.app/docs/installation): Getting started with tiempo in your project
- [TypeScript](https://tiempo.gobrand.app/docs/typescript): Type-safe datetime handling with timezone autocomplete
- [Type Matrix](https://tiempo.gobrand.app/docs/type-matrix): Input, timezone, and return mappings for every public function
- [Recipes](https://tiempo.gobrand.app/docs/recipes): Common timezone-safe datetime workflows
- [AI Resources](https://tiempo.gobrand.app/docs/ai-resources): Machine-readable documentation and Agent Skill discovery

## Conversion

- [toInstant](https://tiempo.gobrand.app/docs/conversion/to-instant): Convert a timeline representation to a Temporal Instant
- [toZonedTime](https://tiempo.gobrand.app/docs/conversion/to-zoned-time): Convert to a timezone-aware ZonedDateTime
- [toPlainDate](https://tiempo.gobrand.app/docs/conversion/to-plain-date): Parse a plain date or extract calendar date from a datetime
- [toPlainTime](https://tiempo.gobrand.app/docs/conversion/to-plain-time): Parse a plain time or extract wall-clock time from a datetime
- [toIso](https://tiempo.gobrand.app/docs/conversion/to-iso): Convert to an ISO 8601 string
- [toIso9075](https://tiempo.gobrand.app/docs/conversion/to-iso9075): Convert to ISO 9075 (SQL) format string
- [toDate](https://tiempo.gobrand.app/docs/conversion/to-date): Convert to a JavaScript Date object

## Current Time

- [now](https://tiempo.gobrand.app/docs/current-time/now): Get the current date and time as a ZonedDateTime
- [today](https://tiempo.gobrand.app/docs/current-time/today): Get today's date as a PlainDate

## Formatting

- [format](https://tiempo.gobrand.app/docs/formatting/format): Format a datetime using date-fns-like format tokens
- [formatPlainDate](https://tiempo.gobrand.app/docs/formatting/format-plain-date): Format a PlainDate using date-fns-like format tokens
- [simpleFormat](https://tiempo.gobrand.app/docs/formatting/simple-format): Human-friendly date/time formatting with explicit control over what to display
- [intlFormatDistance](https://tiempo.gobrand.app/docs/formatting/intl-format-distance): Format the distance between dates as human-readable, internationalized strings

## Arithmetic

- [addYears](https://tiempo.gobrand.app/docs/arithmetic/add-years): Add years to a datetime
- [addQuarters](https://tiempo.gobrand.app/docs/arithmetic/add-quarters): Add quarters to a datetime
- [addMonths](https://tiempo.gobrand.app/docs/arithmetic/add-months): Add months to a datetime
- [addWeeks](https://tiempo.gobrand.app/docs/arithmetic/add-weeks): Add weeks to a datetime
- [addDays](https://tiempo.gobrand.app/docs/arithmetic/add-days): Add days to a datetime (DST-safe)
- [addHours](https://tiempo.gobrand.app/docs/arithmetic/add-hours): Add hours to a datetime
- [addMinutes](https://tiempo.gobrand.app/docs/arithmetic/add-minutes): Add minutes to a datetime
- [addSeconds](https://tiempo.gobrand.app/docs/arithmetic/add-seconds): Add seconds to a datetime
- [subYears](https://tiempo.gobrand.app/docs/arithmetic/sub-years): Subtract years from a datetime
- [subQuarters](https://tiempo.gobrand.app/docs/arithmetic/sub-quarters): Subtract quarters from a datetime
- [subMonths](https://tiempo.gobrand.app/docs/arithmetic/sub-months): Subtract months from a datetime
- [subWeeks](https://tiempo.gobrand.app/docs/arithmetic/sub-weeks): Subtract weeks from a datetime
- [subDays](https://tiempo.gobrand.app/docs/arithmetic/sub-days): Subtract days from a datetime
- [subHours](https://tiempo.gobrand.app/docs/arithmetic/sub-hours): Subtract hours from a datetime
- [subMinutes](https://tiempo.gobrand.app/docs/arithmetic/sub-minutes): Subtract minutes from a datetime
- [subSeconds](https://tiempo.gobrand.app/docs/arithmetic/sub-seconds): Subtract seconds from a datetime

## Boundaries

- [startOfDay](https://tiempo.gobrand.app/docs/boundaries/start-of-day): Get the first moment of the day
- [endOfDay](https://tiempo.gobrand.app/docs/boundaries/end-of-day): Get the last moment of the day
- [startOfWeek](https://tiempo.gobrand.app/docs/boundaries/start-of-week): Get the first boundary of the week (Monday)
- [endOfWeek](https://tiempo.gobrand.app/docs/boundaries/end-of-week): Get the last boundary of the week (Sunday)
- [startOfMonth](https://tiempo.gobrand.app/docs/boundaries/start-of-month): Get the first boundary of the month
- [endOfMonth](https://tiempo.gobrand.app/docs/boundaries/end-of-month): Get the last boundary of the month
- [startOfQuarter](https://tiempo.gobrand.app/docs/boundaries/start-of-quarter): Get the first moment of the quarter
- [endOfQuarter](https://tiempo.gobrand.app/docs/boundaries/end-of-quarter): Get the last moment of the quarter
- [startOfYear](https://tiempo.gobrand.app/docs/boundaries/start-of-year): Get the first boundary of the year
- [endOfYear](https://tiempo.gobrand.app/docs/boundaries/end-of-year): Get the last boundary of the year

## Comparison

- [isBefore](https://tiempo.gobrand.app/docs/comparison/is-before): Check if one datetime is before another
- [isAfter](https://tiempo.gobrand.app/docs/comparison/is-after): Check if one datetime is after another
- [isWithinInterval](https://tiempo.gobrand.app/docs/comparison/is-within-interval): Check if a datetime falls within an interval
- [isFuture](https://tiempo.gobrand.app/docs/comparison/is-future): Check if a datetime is in the future
- [isPast](https://tiempo.gobrand.app/docs/comparison/is-past): Check if a datetime is in the past
- [isSameDay](https://tiempo.gobrand.app/docs/comparison/is-same-day): Check if two datetimes are on the same calendar day
- [isSameWeek](https://tiempo.gobrand.app/docs/comparison/is-same-week): Check if two datetimes are in the same ISO week
- [isSameMonth](https://tiempo.gobrand.app/docs/comparison/is-same-month): Check if two datetimes are in the same calendar month
- [isSameQuarter](https://tiempo.gobrand.app/docs/comparison/is-same-quarter): Check if two datetimes are in the same calendar quarter
- [isSameYear](https://tiempo.gobrand.app/docs/comparison/is-same-year): Check if two datetimes are in the same calendar year

## Difference

- [differenceInYears](https://tiempo.gobrand.app/docs/difference/difference-in-years): Calculate the difference between two dates in years
- [differenceInQuarters](https://tiempo.gobrand.app/docs/difference/difference-in-quarters): Calculate the difference between two dates in quarters
- [differenceInMonths](https://tiempo.gobrand.app/docs/difference/difference-in-months): Calculate the difference between two dates in months
- [differenceInWeeks](https://tiempo.gobrand.app/docs/difference/difference-in-weeks): Calculate the difference between two dates in weeks
- [differenceInDays](https://tiempo.gobrand.app/docs/difference/difference-in-days): Calculate the difference between two dates in days
- [differenceInHours](https://tiempo.gobrand.app/docs/difference/difference-in-hours): Calculate the difference between two dates in hours
- [differenceInMinutes](https://tiempo.gobrand.app/docs/difference/difference-in-minutes): Calculate the difference between two dates in minutes
- [differenceInSeconds](https://tiempo.gobrand.app/docs/difference/difference-in-seconds): Calculate the difference between two dates in seconds

## Intervals

- [eachYearOfInterval](https://tiempo.gobrand.app/docs/intervals/each-year-of-interval): Get all years in an interval as ZonedDateTime array
- [eachQuarterOfInterval](https://tiempo.gobrand.app/docs/intervals/each-quarter-of-interval): Get all quarters in an interval as ZonedDateTime array
- [eachMonthOfInterval](https://tiempo.gobrand.app/docs/intervals/each-month-of-interval): Get all months in an interval as ZonedDateTime array
- [eachWeekOfInterval](https://tiempo.gobrand.app/docs/intervals/each-week-of-interval): Get all weeks (ISO Monday start) in an interval as ZonedDateTime array
- [eachDayOfInterval](https://tiempo.gobrand.app/docs/intervals/each-day-of-interval): Get all days in an interval as ZonedDateTime array
- [eachHourOfInterval](https://tiempo.gobrand.app/docs/intervals/each-hour-of-interval): Get all hours in an interval as ZonedDateTime array
- [eachMinuteOfInterval](https://tiempo.gobrand.app/docs/intervals/each-minute-of-interval): Get all minutes in an interval as ZonedDateTime array

## Utilities

- [getQuarter](https://tiempo.gobrand.app/docs/utilities/get-quarter): Get the quarter (1-4) that a datetime falls in
- [browserTimezone](https://tiempo.gobrand.app/docs/utilities/browser-timezone): Get the browser/device timezone
- [roundToNearestHour](https://tiempo.gobrand.app/docs/utilities/round-to-nearest-hour): Round a datetime to the nearest hour boundary
- [roundToNearestMinute](https://tiempo.gobrand.app/docs/utilities/round-to-nearest-minute): Round a datetime to the nearest minute boundary
- [roundToNearestSecond](https://tiempo.gobrand.app/docs/utilities/round-to-nearest-second): Round a datetime to the nearest second boundary

## Optional

- [addMilliseconds](https://tiempo.gobrand.app/docs/arithmetic/add-milliseconds): Add milliseconds to a datetime
- [addMicroseconds](https://tiempo.gobrand.app/docs/arithmetic/add-microseconds): Add microseconds to a datetime
- [addNanoseconds](https://tiempo.gobrand.app/docs/arithmetic/add-nanoseconds): Add nanoseconds to a datetime
- [subMilliseconds](https://tiempo.gobrand.app/docs/arithmetic/sub-milliseconds): Subtract milliseconds from a datetime
- [subMicroseconds](https://tiempo.gobrand.app/docs/arithmetic/sub-microseconds): Subtract microseconds from a datetime
- [subNanoseconds](https://tiempo.gobrand.app/docs/arithmetic/sub-nanoseconds): Subtract nanoseconds from a datetime
- [isSameHour](https://tiempo.gobrand.app/docs/comparison/is-same-hour): Check if two datetimes are in the same hour
- [isSameMinute](https://tiempo.gobrand.app/docs/comparison/is-same-minute): Check if two datetimes are in the same minute
- [isSameSecond](https://tiempo.gobrand.app/docs/comparison/is-same-second): Check if two datetimes are in the same second
- [isSameMillisecond](https://tiempo.gobrand.app/docs/comparison/is-same-millisecond): Check if two datetimes are in the same millisecond
- [isSameMicrosecond](https://tiempo.gobrand.app/docs/comparison/is-same-microsecond): Check if two datetimes are in the same microsecond
- [isSameNanosecond](https://tiempo.gobrand.app/docs/comparison/is-same-nanosecond): Check if two datetimes are in the same nanosecond
- [isPlainDateBefore](https://tiempo.gobrand.app/docs/comparison/is-plain-date-before): Check if a PlainDate is before another PlainDate
- [isPlainDateAfter](https://tiempo.gobrand.app/docs/comparison/is-plain-date-after): Check if a PlainDate is after another PlainDate
- [isPlainDateEqual](https://tiempo.gobrand.app/docs/comparison/is-plain-date-equal): Check if two PlainDates are equal
- [isPlainTimeBefore](https://tiempo.gobrand.app/docs/comparison/is-plain-time-before): Check if a PlainTime is before another PlainTime
- [isPlainTimeAfter](https://tiempo.gobrand.app/docs/comparison/is-plain-time-after): Check if a PlainTime is after another PlainTime
- [isPlainTimeEqual](https://tiempo.gobrand.app/docs/comparison/is-plain-time-equal): Check if two PlainTimes are equal
- [differenceInMilliseconds](https://tiempo.gobrand.app/docs/difference/difference-in-milliseconds): Calculate the difference between two datetimes in milliseconds
- [differenceInMicroseconds](https://tiempo.gobrand.app/docs/difference/difference-in-microseconds): Calculate the difference between two datetimes in microseconds
- [differenceInNanoseconds](https://tiempo.gobrand.app/docs/difference/difference-in-nanoseconds): Calculate the difference between two datetimes in nanoseconds