temporal-utils 1.0.0 → 1.0.1

package/README.md

@@ -0,0 +1,873 @@
+<!--
+  Links here are NOT rewritten on publish. Any link to another file in this repo
+  must be an absolute GitHub URL rooted at:
+    https://github.com/fullcalendar/temporal-polyfill/blob/main/
+  (use /tree/main/ instead of /blob/main/ when linking a directory)
+-->
+
+# temporal-utils
+
+Small, application-level helpers for working with native [Temporal](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal) objects
+
+Most helpers preserve the input type. For example, passing a
+`Temporal.PlainDateTime` to `startOfMonth` returns a `Temporal.PlainDateTime`,
+while passing a `Temporal.ZonedDateTime` returns a `Temporal.ZonedDateTime`.
+
+## Installation
+
+```
+npm install temporal-utils
+```
+
+`temporal-utils` does not ship a Temporal implementation of its own — a global
+`Temporal` must already exist at runtime. See [Requirements](#requirements).
+
+## Usage
+
+Import the helpers you need from the package root and call them on native
+Temporal objects. Each helper accepts a range of Temporal types and gives you
+back the same type you passed in:
+
+```ts
+import { startOfMonth, diffDays } from 'temporal-utils'
+
+// Pass a PlainDate, get a PlainDate back
+startOfMonth(Temporal.PlainDate.from('2024-07-20')).toString()
+// '2024-07-01'
+
+// Pass a ZonedDateTime, get a ZonedDateTime back
+startOfMonth(
+  Temporal.ZonedDateTime.from('2024-07-20T12:30[America/New_York]'),
+).toString()
+// '2024-07-01T00:00:00-04:00[America/New_York]'
+
+diffDays(
+  Temporal.PlainDate.from('2024-07-01'),
+  Temporal.PlainDate.from('2024-07-20'),
+)
+// 19
+```
+
+## Requirements
+
+`temporal-utils` operates on native `Temporal` objects but does **not** include
+a Temporal implementation of its own. A global `Temporal` must already exist at
+runtime — note that every example below references `Temporal.*` directly to
+build its inputs. Ensure one is present in one of two ways:
+
+- **Native `Temporal`** — available in newer browsers and runtimes, but support
+  is still rolling out and remains incomplete.
+- **A polyfill** — recommended for now. We suggest
+  [`temporal-polyfill`](https://github.com/fullcalendar/temporal-polyfill/blob/main/polyfill/README.md), which installs a global
+  `Temporal`:
+
+  ```ts
+  import 'temporal-polyfill/global'
+  ```
+
+## Function Reference
+
+- [Field Replacement](#field-replacement)
+  - [`withDayOfYear`](#withdayofyear)
+  - [`withDayOfWeek`](#withdayofweek)
+  - [`withWeekOfYear`](#withweekofyear)
+- [Difference Helpers](#difference-helpers)
+  - [`diffYears`](#diffyears)
+  - [`diffMonths`](#diffmonths)
+  - [`diffWeeks`](#diffweeks)
+  - [`diffDays`](#diffdays)
+  - [`diffHours`](#diffhours)
+  - [`diffMinutes`](#diffminutes)
+  - [`diffSeconds`](#diffseconds)
+  - [`diffMilliseconds`](#diffmilliseconds)
+  - [`diffMicroseconds`](#diffmicroseconds)
+  - [`diffNanoseconds`](#diffnanoseconds)
+- [Rounding Helpers](#rounding-helpers)
+  - [`roundToYear`](#roundtoyear)
+  - [`roundToMonth`](#roundtomonth)
+  - [`roundToWeek`](#roundtoweek)
+  - [⚠️ `roundToDay`](#roundtoday)
+  - [⚠️ `roundToHour`](#roundtohour)
+  - [⚠️ `roundToMinute`](#roundtominute)
+  - [⚠️ `roundToSecond`](#roundtosecond)
+  - [⚠️ `roundToMillisecond`](#roundtomillisecond)
+  - [⚠️ `roundToMicrosecond`](#roundtomicrosecond)
+- [Start Of Unit](#start-of-unit)
+  - [`startOfYear`](#startofyear)
+  - [`startOfMonth`](#startofmonth)
+  - [`startOfWeek`](#startofweek)
+  - [`startOfDay`](#startofday)
+  - [`startOfHour`](#startofhour)
+  - [`startOfMinute`](#startofminute)
+  - [`startOfSecond`](#startofsecond)
+  - [`startOfMillisecond`](#startofmillisecond)
+  - [`startOfMicrosecond`](#startofmicrosecond)
+- [End Of Unit](#end-of-unit)
+  - [`endOfYear`](#endofyear)
+  - [`endOfMonth`](#endofmonth)
+  - [`endOfWeek`](#endofweek)
+  - [`endOfDay`](#endofday)
+  - [`endOfHour`](#endofhour)
+  - [`endOfMinute`](#endofminute)
+  - [`endOfSecond`](#endofsecond)
+  - [`endOfMillisecond`](#endofmillisecond)
+  - [`endOfMicrosecond`](#endofmicrosecond)
+- [Shared Types](#shared-types)
+  - [`RoundingMode`](#roundingmode)
+  - [`RoundingMathOptions`](#roundingmathoptions)
+
+## Field Replacement
+
+These helpers fill gaps where Temporal exposes calendar-derived fields such as
+`dayOfYear`, `dayOfWeek`, and `weekOfYear`, but does not provide direct
+`with({ ... })` fields for replacing them.
+
+All field replacement helpers:
+
+- accept `Temporal.PlainDate`, `Temporal.PlainDateTime`, or
+  `Temporal.ZonedDateTime`
+- truncate numeric input toward zero before applying it
+- accept Temporal field overflow options: `{ overflow: 'constrain' }` or
+  `{ overflow: 'reject' }`
+- default overflow behavior to `'constrain'`
+
+### `withDayOfYear`
+
+Signature:
+
+```ts
+function withDayOfYear<
+  T extends Temporal.PlainDate | Temporal.PlainDateTime | Temporal.ZonedDateTime,
+>(
+  date: T,
+  dayOfYear: number,
+  options?: Temporal.OverflowOptions,
+): T
+```
+
+Returns the same calendar year with `dayOfYear` replaced. The time, time zone,
+and calendar are preserved.
+
+```ts
+import { withDayOfYear } from 'temporal-utils'
+
+const date = Temporal.PlainDate.from('2024-02-27')
+
+withDayOfYear(date, 5).toString()
+// '2024-01-05'
+
+withDayOfYear(date, 500).toString()
+// '2024-12-31'
+
+withDayOfYear(date, 500, { overflow: 'reject' })
+// RangeError
+```
+
+### `withDayOfWeek`
+
+Signature:
+
+```ts
+function withDayOfWeek<
+  T extends Temporal.PlainDate | Temporal.PlainDateTime | Temporal.ZonedDateTime,
+>(
+  date: T,
+  dayOfWeek: number,
+  options?: Temporal.OverflowOptions,
+): T
+```
+
+Returns the same ISO week with `dayOfWeek` replaced. Temporal uses ISO weekday
+numbers: Monday is `1` and Sunday is `7`.
+
+```ts
+import { withDayOfWeek } from 'temporal-utils'
+
+const date = Temporal.PlainDate.from('2024-02-27') // Tuesday
+
+withDayOfWeek(date, 4).toString()
+// '2024-02-29'
+
+withDayOfWeek(date, 8).toString()
+// '2024-03-03'
+```
+
+### `withWeekOfYear`
+
+Signature:
+
+```ts
+function withWeekOfYear<
+  T extends Temporal.PlainDate | Temporal.PlainDateTime | Temporal.ZonedDateTime,
+>(
+  date: T,
+  weekOfYear: number,
+  options?: Temporal.OverflowOptions,
+): T
+```
+
+Returns the same ISO week-year with `weekOfYear` replaced, preserving the
+current day of week. This helper is ISO-only and throws a `RangeError` for
+calendars where Temporal does not expose ISO week fields.
+
+```ts
+import { withWeekOfYear } from 'temporal-utils'
+
+const date = Temporal.PlainDate.from('2024-02-27') // Tuesday, week 9
+
+withWeekOfYear(date, 27).toString()
+// '2024-07-02'
+
+withWeekOfYear(date.withCalendar('hebrew'), 27)
+// RangeError
+```
+
+## Difference Helpers
+
+Single-unit difference helpers return a number for `date0.until(date1)`. The
+helpers are directional: reversing the arguments reverses the sign.
+
+If no options are supplied, the result is the exact total in the requested unit.
+Pass a `RoundingMode` string or a `RoundingMathOptions` object to request Temporal
+rounding behavior for that unit.
+
+```ts
+import { diffDays, diffMonths } from 'temporal-utils'
+
+const start = Temporal.PlainDate.from('2024-02-20')
+const end = Temporal.PlainDate.from('2024-04-10')
+
+diffMonths(start, end)
+// approximately 1.677...
+
+diffMonths(start, end, 'floor')
+// 1
+
+diffDays(start, end, { roundingMode: 'ceil', roundingIncrement: 7 })
+// 56
+```
+
+Date and calendar unit helpers use `relativeTo` internally so totals account
+for calendar units. For `Temporal.ZonedDateTime`, totals also account for
+time-zone transitions. Time-unit helpers produce elapsed-time totals.
+
+### `diffYears`
+
+Signature:
+
+```ts
+function diffYears(
+  date0: Temporal.PlainYearMonth | Temporal.PlainDate | Temporal.PlainDateTime | Temporal.ZonedDateTime,
+  date1: Temporal.PlainYearMonth | Temporal.PlainDate | Temporal.PlainDateTime | Temporal.ZonedDateTime,
+  options?: RoundingMode | RoundingMathOptions,
+): number
+```
+
+Returns the difference in years. Supported input types are
+`Temporal.PlainYearMonth`, `Temporal.PlainDate`, `Temporal.PlainDateTime`, and
+`Temporal.ZonedDateTime`.
+
+### `diffMonths`
+
+Signature:
+
+```ts
+function diffMonths(
+  date0: Temporal.PlainYearMonth | Temporal.PlainDate | Temporal.PlainDateTime | Temporal.ZonedDateTime,
+  date1: Temporal.PlainYearMonth | Temporal.PlainDate | Temporal.PlainDateTime | Temporal.ZonedDateTime,
+  options?: RoundingMode | RoundingMathOptions,
+): number
+```
+
+Returns the difference in months. Supported input types are
+`Temporal.PlainYearMonth`, `Temporal.PlainDate`, `Temporal.PlainDateTime`, and
+`Temporal.ZonedDateTime`.
+
+### `diffWeeks`
+
+Signature:
+
+```ts
+function diffWeeks(
+  date0: Temporal.PlainDate | Temporal.PlainDateTime | Temporal.ZonedDateTime,
+  date1: Temporal.PlainDate | Temporal.PlainDateTime | Temporal.ZonedDateTime,
+  options?: RoundingMode | RoundingMathOptions,
+): number
+```
+
+Returns the difference in weeks. Supported input types are `Temporal.PlainDate`,
+`Temporal.PlainDateTime`, and `Temporal.ZonedDateTime`.
+
+### `diffDays`
+
+Signature:
+
+```ts
+function diffDays(
+  date0: Temporal.PlainDate | Temporal.PlainDateTime | Temporal.ZonedDateTime,
+  date1: Temporal.PlainDate | Temporal.PlainDateTime | Temporal.ZonedDateTime,
+  options?: RoundingMode | RoundingMathOptions,
+): number
+```
+
+Returns the difference in days. Supported input types are `Temporal.PlainDate`,
+`Temporal.PlainDateTime`, and `Temporal.ZonedDateTime`.
+
+### `diffHours`
+
+Signature:
+
+```ts
+function diffHours(
+  date0: Temporal.Instant | Temporal.PlainTime | Temporal.PlainDateTime | Temporal.ZonedDateTime,
+  date1: Temporal.Instant | Temporal.PlainTime | Temporal.PlainDateTime | Temporal.ZonedDateTime,
+  options?: RoundingMode | RoundingMathOptions,
+): number
+```
+
+Returns the difference in hours. Supported input types are `Temporal.Instant`,
+`Temporal.PlainTime`, `Temporal.PlainDateTime`, and `Temporal.ZonedDateTime`.
+
+### `diffMinutes`
+
+Signature:
+
+```ts
+function diffMinutes(
+  date0: Temporal.Instant | Temporal.PlainTime | Temporal.PlainDateTime | Temporal.ZonedDateTime,
+  date1: Temporal.Instant | Temporal.PlainTime | Temporal.PlainDateTime | Temporal.ZonedDateTime,
+  options?: RoundingMode | RoundingMathOptions,
+): number
+```
+
+Returns the difference in minutes. Supported input types are `Temporal.Instant`,
+`Temporal.PlainTime`, `Temporal.PlainDateTime`, and `Temporal.ZonedDateTime`.
+
+### `diffSeconds`
+
+Signature:
+
+```ts
+function diffSeconds(
+  date0: Temporal.Instant | Temporal.PlainTime | Temporal.PlainDateTime | Temporal.ZonedDateTime,
+  date1: Temporal.Instant | Temporal.PlainTime | Temporal.PlainDateTime | Temporal.ZonedDateTime,
+  options?: RoundingMode | RoundingMathOptions,
+): number
+```
+
+Returns the difference in seconds. Supported input types are `Temporal.Instant`,
+`Temporal.PlainTime`, `Temporal.PlainDateTime`, and `Temporal.ZonedDateTime`.
+
+### `diffMilliseconds`
+
+Signature:
+
+```ts
+function diffMilliseconds(
+  date0: Temporal.Instant | Temporal.PlainTime | Temporal.PlainDateTime | Temporal.ZonedDateTime,
+  date1: Temporal.Instant | Temporal.PlainTime | Temporal.PlainDateTime | Temporal.ZonedDateTime,
+  options?: RoundingMode | RoundingMathOptions,
+): number
+```
+
+Returns the difference in milliseconds. Supported input types are
+`Temporal.Instant`, `Temporal.PlainTime`, `Temporal.PlainDateTime`, and
+`Temporal.ZonedDateTime`.
+
+### `diffMicroseconds`
+
+Signature:
+
+```ts
+function diffMicroseconds(
+  date0: Temporal.Instant | Temporal.PlainTime | Temporal.PlainDateTime | Temporal.ZonedDateTime,
+  date1: Temporal.Instant | Temporal.PlainTime | Temporal.PlainDateTime | Temporal.ZonedDateTime,
+  options?: RoundingMode | RoundingMathOptions,
+): number
+```
+
+Returns the difference in microseconds. Supported input types are
+`Temporal.Instant`, `Temporal.PlainTime`, `Temporal.PlainDateTime`, and
+`Temporal.ZonedDateTime`.
+
+### `diffNanoseconds`
+
+Signature:
+
+```ts
+function diffNanoseconds(
+  date0: Temporal.Instant | Temporal.PlainTime | Temporal.PlainDateTime | Temporal.ZonedDateTime,
+  date1: Temporal.Instant | Temporal.PlainTime | Temporal.PlainDateTime | Temporal.ZonedDateTime,
+  options?: RoundingMode | RoundingMathOptions,
+): number
+```
+
+Returns the difference in nanoseconds. Supported input types are
+`Temporal.Instant`, `Temporal.PlainTime`, `Temporal.PlainDateTime`, and
+`Temporal.ZonedDateTime`.
+
+## Rounding Helpers
+
+Calendar rounding helpers return the closest start of the named unit. They are
+useful because Temporal's native `.round()` APIs cover day and smaller units,
+but not every larger calendar unit in a uniform way across date-like types.
+
+If `options` or `options.roundingMode` is omitted, `roundingMode` defaults to
+`'halfExpand'`. Pass a `RoundingMode` string as shorthand for
+`{ roundingMode }`.
+
+`RoundingMathOptions` must not include `smallestUnit`; the helper name supplies
+the unit. For the year, month, and week helpers, `roundingIncrement` must be
+omitted or `1`.
+
+⚠️ The day and smaller `roundTo*` helpers are exported as codemod targets, not
+as recommended hand-written API. In application code, prefer native Temporal
+`.round()` directly:
+
+```ts
+dateTime.round({ smallestUnit: 'day' })
+time.round({ smallestUnit: 'minute', roundingMode: 'ceil' })
+instant.round({ smallestUnit: 'second' })
+```
+
+```ts
+import { roundToMonth, roundToWeek, roundToYear } from 'temporal-utils'
+
+const dateTime = Temporal.PlainDateTime.from('2024-07-20T12:30:00')
+
+roundToYear(dateTime).toString()
+// '2025-01-01T00:00:00'
+
+roundToMonth(dateTime, 'floor').toString()
+// '2024-07-01T00:00:00'
+
+roundToWeek(dateTime, { roundingMode: 'floor' }).toString()
+// '2024-07-15T00:00:00'
+```
+
+### `roundToYear`
+
+Signature:
+
+```ts
+function roundToYear<
+  T extends
+    | Temporal.PlainYearMonth
+    | Temporal.PlainDate
+    | Temporal.PlainDateTime
+    | Temporal.ZonedDateTime,
+>(date: T, options?: RoundingMode | RoundingMathOptions): T
+```
+
+Rounds to the nearest year boundary. Supported input types are
+`Temporal.PlainYearMonth`, `Temporal.PlainDate`, `Temporal.PlainDateTime`, and
+`Temporal.ZonedDateTime`.
+
+### `roundToMonth`
+
+Signature:
+
+```ts
+function roundToMonth<
+  T extends Temporal.PlainDate | Temporal.PlainDateTime | Temporal.ZonedDateTime,
+>(date: T, options?: RoundingMode | RoundingMathOptions): T
+```
+
+Rounds to the nearest month boundary. Supported input types are
+`Temporal.PlainDate`, `Temporal.PlainDateTime`, and `Temporal.ZonedDateTime`.
+
+### `roundToWeek`
+
+Signature:
+
+```ts
+function roundToWeek<
+  T extends Temporal.PlainDate | Temporal.PlainDateTime | Temporal.ZonedDateTime,
+>(date: T, options?: RoundingMode | RoundingMathOptions): T
+```
+
+Rounds to the nearest ISO week boundary. Supported input types are
+`Temporal.PlainDate`, `Temporal.PlainDateTime`, and `Temporal.ZonedDateTime`.
+
+<a id="roundtoday"></a>
+
+### ⚠️ `roundToDay`
+
+Signature:
+
+```ts
+function roundToDay<T extends Temporal.PlainDateTime | Temporal.ZonedDateTime>(
+  date: T,
+  options?: RoundingMode | RoundingMathOptions,
+): T
+```
+
+Codemod target for rounding to the nearest day. Prefer
+`dateTime.round({ smallestUnit: 'day' })` in hand-written code.
+
+<a id="roundtohour"></a>
+
+### ⚠️ `roundToHour`
+
+Signature:
+
+```ts
+function roundToHour<
+  T extends Temporal.Instant | Temporal.PlainTime | Temporal.PlainDateTime | Temporal.ZonedDateTime,
+>(date: T, options?: RoundingMode | RoundingMathOptions): T
+```
+
+Codemod target for rounding to the nearest hour. Prefer
+`value.round({ smallestUnit: 'hour' })` in hand-written code.
+
+<a id="roundtominute"></a>
+
+### ⚠️ `roundToMinute`
+
+Signature:
+
+```ts
+function roundToMinute<
+  T extends Temporal.Instant | Temporal.PlainTime | Temporal.PlainDateTime | Temporal.ZonedDateTime,
+>(date: T, options?: RoundingMode | RoundingMathOptions): T
+```
+
+Codemod target for rounding to the nearest minute. Prefer
+`value.round({ smallestUnit: 'minute' })` in hand-written code.
+
+<a id="roundtosecond"></a>
+
+### ⚠️ `roundToSecond`
+
+Signature:
+
+```ts
+function roundToSecond<
+  T extends Temporal.Instant | Temporal.PlainTime | Temporal.PlainDateTime | Temporal.ZonedDateTime,
+>(date: T, options?: RoundingMode | RoundingMathOptions): T
+```
+
+Codemod target for rounding to the nearest second. Prefer
+`value.round({ smallestUnit: 'second' })` in hand-written code.
+
+<a id="roundtomillisecond"></a>
+
+### ⚠️ `roundToMillisecond`
+
+Signature:
+
+```ts
+function roundToMillisecond<
+  T extends Temporal.Instant | Temporal.PlainTime | Temporal.PlainDateTime | Temporal.ZonedDateTime,
+>(date: T, options?: RoundingMode | RoundingMathOptions): T
+```
+
+Codemod target for rounding to the nearest millisecond. Prefer
+`value.round({ smallestUnit: 'millisecond' })` in hand-written code.
+
+<a id="roundtomicrosecond"></a>
+
+### ⚠️ `roundToMicrosecond`
+
+Signature:
+
+```ts
+function roundToMicrosecond<
+  T extends Temporal.Instant | Temporal.PlainTime | Temporal.PlainDateTime | Temporal.ZonedDateTime,
+>(date: T, options?: RoundingMode | RoundingMathOptions): T
+```
+
+Codemod target for rounding to the nearest microsecond. Prefer
+`value.round({ smallestUnit: 'microsecond' })` in hand-written code.
+
+## Start Of Unit
+
+Start helpers truncate smaller fields to the beginning of the named unit.
+`startOfWeek` uses ISO weeks, so the week starts on Monday.
+
+For `Temporal.ZonedDateTime`, these helpers use Temporal's own field
+replacement behavior. If local midnight is skipped by a time-zone transition,
+Temporal resolves to the first real instant after the skipped wall time.
+
+```ts
+import { startOfMonth, startOfWeek } from 'temporal-utils'
+
+const zdt = Temporal.ZonedDateTime.from('2024-07-20T12:30:00[America/New_York]')
+
+startOfMonth(zdt).toString()
+// '2024-07-01T00:00:00-04:00[America/New_York]'
+
+startOfWeek(zdt).toString()
+// '2024-07-15T00:00:00-04:00[America/New_York]'
+```
+
+### `startOfYear`
+
+Signature:
+
+```ts
+function startOfYear<
+  T extends
+    | Temporal.PlainYearMonth
+    | Temporal.PlainDate
+    | Temporal.PlainDateTime
+    | Temporal.ZonedDateTime,
+>(date: T): T
+```
+
+Returns the start of the current year. For `Temporal.PlainYearMonth`, this is
+January of the same year.
+
+### `startOfMonth`
+
+Signature:
+
+```ts
+function startOfMonth<
+  T extends Temporal.PlainDate | Temporal.PlainDateTime | Temporal.ZonedDateTime,
+>(date: T): T
+```
+
+Returns the start of the current month.
+
+### `startOfWeek`
+
+Signature:
+
+```ts
+function startOfWeek<
+  T extends Temporal.PlainDate | Temporal.PlainDateTime | Temporal.ZonedDateTime,
+>(date: T): T
+```
+
+Returns the start of the current ISO week, which is Monday.
+
+### `startOfDay`
+
+Signature:
+
+```ts
+function startOfDay<T extends Temporal.PlainDateTime | Temporal.ZonedDateTime>(
+  dateTime: T,
+): T
+```
+
+Returns midnight at the start of the current day.
+
+### `startOfHour`
+
+Signature:
+
+```ts
+function startOfHour<
+  T extends Temporal.PlainTime | Temporal.PlainDateTime | Temporal.ZonedDateTime,
+>(dateTime: T): T
+```
+
+Returns the start of the current hour.
+
+### `startOfMinute`
+
+Signature:
+
+```ts
+function startOfMinute<
+  T extends Temporal.PlainTime | Temporal.PlainDateTime | Temporal.ZonedDateTime,
+>(dateTime: T): T
+```
+
+Returns the start of the current minute.
+
+### `startOfSecond`
+
+Signature:
+
+```ts
+function startOfSecond<
+  T extends Temporal.PlainTime | Temporal.PlainDateTime | Temporal.ZonedDateTime,
+>(dateTime: T): T
+```
+
+Returns the start of the current second.
+
+### `startOfMillisecond`
+
+Signature:
+
+```ts
+function startOfMillisecond<
+  T extends Temporal.PlainTime | Temporal.PlainDateTime | Temporal.ZonedDateTime,
+>(dateTime: T): T
+```
+
+Returns the start of the current millisecond.
+
+### `startOfMicrosecond`
+
+Signature:
+
+```ts
+function startOfMicrosecond<
+  T extends Temporal.PlainTime | Temporal.PlainDateTime | Temporal.ZonedDateTime,
+>(dateTime: T): T
+```
+
+Returns the start of the current microsecond.
+
+## End Of Unit
+
+End helpers return the last representable value before the next unit begins.
+For date-time and zoned date-time values, this means one nanosecond before the
+exclusive end. For date-only values, it means one day before the exclusive end.
+For `Temporal.PlainYearMonth`, `endOfYear` returns December of the same year.
+
+```ts
+import { endOfDay, endOfMonth } from 'temporal-utils'
+
+const dateTime = Temporal.PlainDateTime.from('2024-07-20T12:30:00')
+
+endOfDay(dateTime).toString()
+// '2024-07-20T23:59:59.999999999'
+
+endOfMonth(dateTime).toString()
+// '2024-07-31T23:59:59.999999999'
+```
+
+### `endOfYear`
+
+Signature:
+
+```ts
+function endOfYear<
+  T extends
+    | Temporal.PlainYearMonth
+    | Temporal.PlainDate
+    | Temporal.PlainDateTime
+    | Temporal.ZonedDateTime,
+>(date: T): T
+```
+
+Returns the last representable value in the current year.
+
+### `endOfMonth`
+
+Signature:
+
+```ts
+function endOfMonth<
+  T extends Temporal.PlainDate | Temporal.PlainDateTime | Temporal.ZonedDateTime,
+>(date: T): T
+```
+
+Returns the last representable value in the current month.
+
+### `endOfWeek`
+
+Signature:
+
+```ts
+function endOfWeek<
+  T extends Temporal.PlainDate | Temporal.PlainDateTime | Temporal.ZonedDateTime,
+>(date: T): T
+```
+
+Returns the last representable value in the current ISO week.
+
+### `endOfDay`
+
+Signature:
+
+```ts
+function endOfDay<T extends Temporal.PlainDateTime | Temporal.ZonedDateTime>(
+  date: T,
+): T
+```
+
+Returns the last representable value in the current day.
+
+### `endOfHour`
+
+Signature:
+
+```ts
+function endOfHour<
+  T extends Temporal.PlainTime | Temporal.PlainDateTime | Temporal.ZonedDateTime,
+>(date: T): T
+```
+
+Returns the last representable value in the current hour.
+
+### `endOfMinute`
+
+Signature:
+
+```ts
+function endOfMinute<
+  T extends Temporal.PlainTime | Temporal.PlainDateTime | Temporal.ZonedDateTime,
+>(date: T): T
+```
+
+Returns the last representable value in the current minute.
+
+### `endOfSecond`
+
+Signature:
+
+```ts
+function endOfSecond<
+  T extends Temporal.PlainTime | Temporal.PlainDateTime | Temporal.ZonedDateTime,
+>(date: T): T
+```
+
+Returns the last representable value in the current second.
+
+### `endOfMillisecond`
+
+Signature:
+
+```ts
+function endOfMillisecond<
+  T extends Temporal.PlainTime | Temporal.PlainDateTime | Temporal.ZonedDateTime,
+>(date: T): T
+```
+
+Returns the last representable value in the current millisecond.
+
+### `endOfMicrosecond`
+
+Signature:
+
+```ts
+function endOfMicrosecond<
+  T extends Temporal.PlainTime | Temporal.PlainDateTime | Temporal.ZonedDateTime,
+>(date: T): T
+```
+
+Returns the last representable value in the current microsecond.
+
+## Shared Types
+
+### `RoundingMode`
+
+Type:
+
+```ts
+import type { RoundingMode } from 'temporal-utils'
+```
+
+`RoundingMode` is shared by the rounding and difference helpers.
+
+### `RoundingMathOptions`
+
+Type:
+
+```ts
+import type { RoundingMathOptions } from 'temporal-utils'
+```
+
+`RoundingMathOptions` contains the rounding fields used by single-unit math
+helpers.
+
+The unit is implied by the helper name. For example, `roundToWeek(date,
+options)` forces `smallestUnit: 'week'` internally, and `diffMonths(date0,
+date1, options)` forces month-based difference math internally.