# DateTime An immutable date and time in an IANA time zone. Backed by the TC39 Temporal API where the runtime provides it, and by `Intl.DateTimeFormat` everywhere else. Both paths implement the same semantics, so behaviour does not change with the host. Time-zone support needs no bundled database and no dependency. Months and days are 1-based and `dayOfWeek` runs 1 (Monday) to 7 (Sunday), following Temporal and ISO-8601 rather than the legacy `Date`. Every method returns a new instance; nothing mutates. ## Parameters - **input** — An ISO-8601 string, epoch milliseconds, a `Date`, another `DateTime`, or a wall-clock fields object. Omit it for the current time. - **options** — `timeZone` (IANA id, default `'UTC'`) and `disambiguation` (`'compatible'` | `'earlier'` | `'later'` | `'reject'`, default `'compatible'`). Parsing is strict ISO-8601 and throws a `RangeError` rather than yielding an `Invalid Date`, because `Date.parse` is implementation-defined outside the ISO subset and disagrees across runtimes. ### Statics - `DateTime.now(timeZone?)` — the current time. - `DateTime.compare(a, b)` — comparator for `Array.prototype.sort`. - `DateTime.hasTemporal` — whether this runtime provides Temporal. - `DateTime.fromTemporal(value)` — from a `Temporal.ZonedDateTime` or `Temporal.Instant`. ### Getters `year`, `month`, `day`, `hour`, `minute`, `second`, `millisecond`, `dayOfWeek`, `dayOfYear`, `weekOfYear`, `weekYear`, `daysInMonth`, `daysInYear`, `inLeapYear`, `timeZone`, `offset`, `offsetMs`, `epochMs`. ### Methods - `add(duration)` / `subtract(duration)` — calendar and/or exact units. - `with(fields)` — replace wall-clock fields, keeping the zone. - `withTimeZone(tz)` — keep the instant, move the clock. - `startOf(unit)` / `endOf(unit)` — truncate. Weeks start on Monday; `endOf` returns the last millisecond. - `diff(other, unit)` — signed `this − other`. - `compare(other)`, `equals(other)`, `isBefore(other)`, `isAfter(other)`, `isBetween(start, end)`. - `format(pattern, locale?)`, `toLocaleString(locale?, options?)`. - `toISOString()`, `toJSON()`, `toString()`, `toDate()`, `valueOf()`, `toTemporal()`. Units are `'year'`, `'month'`, `'week'`, `'day'`, `'hour'`, `'minute'`, `'second'` and `'millisecond'`. ## Example ```js const dt = new DateTime('2026-03-08T01:30:00', { timeZone: 'America/New_York' }); dt.format('yyyy-MM-dd HH:mm ZZ'); //=> '2026-03-08 01:30 -05:00' dt.add({ hours: 1 }).format('HH:mm ZZ'); //=> '03:00 -04:00' (DST gap skipped) dt.add({ days: 1 }).format('HH:mm ZZ'); //=> '01:30 -04:00' (wall clock kept) dt.withTimeZone('Asia/Kolkata').format('yyyy-MM-dd HH:mm'); //=> '2026-03-08 12:00' dt.startOf('month').toISOString(); //=> '2026-03-01T00:00:00.000-05:00[America/New_York]' ``` Calendar units (`years`, `months`, `weeks`, `days`) move the wall clock, so adding a day across a DST boundary keeps the local time and may advance 23 or 25 real hours. Exact units (`hours` and below) move the instant. Month arithmetic clamps: ```js new DateTime('2026-01-31').add({ months: 1 }).format('yyyy-MM-dd'); //=> '2026-02-28' ``` `diff` counts whole units for `year`, `month`, `week` and `day`, truncated toward zero, and returns fractional elapsed time for `hour` and below. ### DST disambiguation A wall-clock time can be missing or repeated at a transition: ```js const wall = '2026-03-08T02:30:00'; // never happens in New York const timeZone = 'America/New_York'; new DateTime(wall, { timeZone }).format('HH:mm ZZ'); //=> '03:30 -04:00' — 'compatible' shifts a gap forward new DateTime(wall, { timeZone, disambiguation: 'earlier' }).format('HH:mm ZZ'); //=> '01:30 -05:00' new DateTime(wall, { timeZone, disambiguation: 'reject' }); // throws RangeError ``` For an overlap — a wall time that happens twice — `'compatible'` takes the earlier instant. ### Format tokens | Token | Output | Token | Output | | --------------------- | --------------------- | -------- | ---------------- | | `yyyy` `yy` | `2026` `26` | `HH` `H` | hour, 0–23 | | `MMMM` `MMM` `MM` `M` | `July` `Jul` `07` `7` | `hh` `h` | hour, 1–12 | | `dd` `d` | `29` `29` | `mm` `m` | minute | | `EEEE` `EEE` | `Wednesday` `Wed` | `ss` `s` | second | | `DDD` | day of year | `SSS` | millisecond | | `ww` | ISO week | `a` | `AM` / `PM` | | `zzz` | `Asia/Kolkata` | `ZZ` `Z` | `+05:30` `+0530` | Text in single quotes is literal. Only month and weekday names depend on `locale`; everything else is locale-independent, so a pattern produces the same bytes on every runtime. ### Runtime support The whole API works on every runtime — only the machinery underneath changes. | Runtime | Backend | | ------------------------------------------ | -------- | | Node.js 26+, Deno, ES-Runtime | Temporal | | Chrome 144+, Edge 144+, Firefox 139+ | Temporal | | Node.js 24 / 25 with `--harmony-temporal` | Temporal | | Node.js 22 and earlier, Bun, LLRT, Safari | `Intl` | `toTemporal` and `DateTime.fromTemporal` are the only members that need Temporal and throw where it is absent; check `DateTime.hasTemporal` first. On LLRT, `Intl` ignores locales and component options, so month names, weekday names and `toLocaleString` do not work there. Numeric tokens, time zones and all arithmetic are unaffected.