Temporal (Concept Level)

## The conflation Temporal is undoing A single legacy `Date` value is simultaneously an epoch timestamp and, through its local getters, a wall-clock reading in whatever zone the machine happens to be configured for. Those are two different kinds of fact, and code that mixes them produces bugs that only appear on machines in other zones. Temporal's central design move is to give each kind of fact its own immutable type, and to make you say out loud what is missing whenever you move between them. (Temporal is a Stage 3 TC39 proposal. As of 2026 Firefox ships it and other engines are in progress; most production code still reaches it through the official `@js-temporal/polyfill`.) ## Temporal.Instant — the exact time An `Instant` is a point on the global timeline: nanoseconds since the Unix epoch, exposed as `instant.epochNanoseconds` (a BigInt) and `instant.epochMilliseconds` (a Number). It has no calendar and no time zone, so it has no `.year`, no `.hour`, and no `.dayOfWeek` — asking "what date is this Instant?" is a category error until you name a zone. Two Instants can be ordered without any further context (`Temporal.Instant.compare(a, b)`), because exact times are globally comparable. Its `toString()` produces a `Z`-suffixed ISO string such as `2026-06-01T17:00:00Z`. Because it has no calendar, `Instant` arithmetic accepts only exact-time units — hours, minutes, seconds and smaller. You cannot add a month to an Instant, because "a month" has no length without a calendar. ## Temporal.PlainDateTime — the wall-clock reading A `PlainDateTime` is a date and a time of day with a calendar but *no zone and no offset*: `2026-06-01T19:00`. It is what a wall clock or a paper form says. Crucially it does not identify a moment — `2026-06-01T19:00` happened at a different instant in Berlin than in São Paulo, and on a DST transition day a given wall-clock reading may not exist at all, or may exist twice. The same family includes narrower plain types for the cases where you genuinely have less information: `Temporal.PlainDate` (a calendar day, e.g. a date of birth), `Temporal.PlainTime` (a time of day, e.g. a shop's opening hour), `Temporal.PlainYearMonth` (a card expiry) and `Temporal.PlainMonthDay` (a recurring anniversary). Choosing the narrowest type that fits is itself a correctness tool: a `PlainDate` cannot accidentally acquire a spurious midnight-in-UTC. ## Temporal.ZonedDateTime — both at once A `ZonedDateTime` carries an exact time, an IANA time-zone ID and a calendar ID together. It therefore answers both questions: `zdt.epochNanoseconds` gives the exact time, `zdt.hour` gives the wall-clock reading, `zdt.timeZoneId` gives `"Europe/Berlin"`, `zdt.offset` gives `"+02:00"`, and `zdt.calendarId` gives `"iso8601"`. Its string form round-trips all of it: ```js Temporal.ZonedDateTime.from('2026-06-01T19:00[Europe/Berlin]').toString(); // '2026-06-01T19:00:00+02:00[Europe/Berlin]' ``` The zone ID matters more than the offset. An offset like `+02:00` is a snapshot of one moment's rules; the ID is the rule set itself, so arithmetic across a DST boundary still lands on the right wall-clock time. ## The conversion graph Going from more information to less is lossy but unambiguous, so it needs no arguments: ```js const zdt = Temporal.ZonedDateTime.from('2026-06-01T19:00[Europe/Berlin]'); zdt.toInstant(); // drops zone + calendar zdt.toPlainDateTime(); // drops zone, keeps wall clock zdt.toPlainDate(); // just the calendar day ``` Going the other way requires you to supply what is missing, which is where Temporal refuses to guess: ```js const instant = Temporal.Instant.from('2026-06-01T17:00:00Z'); instant.toZonedDateTimeISO('Europe/Berlin'); // 2026-06-01T19:00:00+02:00[Europe/Berlin] const pdt = Temporal.PlainDateTime.from('2026-06-01T19:00'); pdt.toZonedDateTime('Europe/Berlin').toInstant().equals(instant); // true ``` There is no `PlainDateTime.prototype.toInstant()` at all — the type system makes the missing zone impossible to forget. ## Picking the right one A useful rule: if the fact is "something happened", it is an exact time and belongs in an `Instant` — log lines, audit records, payment captures. If the fact is "a human will read this on a clock", it is a wall-clock value and belongs in a `PlainDateTime` (or a narrower plain type) together with the zone it belongs to. `ZonedDateTime` is what you compute with when you need both views at once — anything doing calendar arithmetic in a real place, such as "the same time tomorrow" or "the start of the business day". Current time is obtained per shape: `Temporal.Now.instant()`, `Temporal.Now.zonedDateTimeISO()`, `Temporal.Now.plainDateISO()` — again, you choose the precision of the truth you want rather than getting one type that pretends to be all three.