Temporal API Date & Time

JavaScript's Date object is notoriously problematic: it's mutable, months are 0-indexed, timezone handling is inconsistent, and parsing is unreliable. The Temporal API (TC39 Stage 3 proposal) addresses these issues with immutable objects, clear semantics, and explicit timezone support. In discussions: 'use Temporal' means avoid Date's gotchas for calendar arithmetic and timezone-aware calculations.

Temporal.ZonedDateTime represents a point in time in a specific timezone with DST rules applied. Unlike a UTC offset (+02:00), a ZonedDateTime knows the actual timezone (Europe/Warsaw) and handles daylight saving transitions correctly. In discussions: 'use ZonedDateTime when you need to display dates to users in their local time with correct DST handling' — not just for logging or API responses.

Immutability in Temporal means operations like date.add({ days: 1 }) return a new Temporal object without modifying the original. With Date, date.setDate(date.getDate() + 1) mutates the original — a common source of bugs. Immutability makes date calculations predictable and safe to share across functions. In code reviews: 'Temporal is immutable' is often mentioned as a safety advantage.

Temporal.PlainDate represents a date (year, month, day) with no time and no timezone. This is correct for birthdays, holidays, or any concept that is 'just a date' regardless of timezone. Using ZonedDateTime or a timestamp for a birthday would cause incorrect off-by-one-day errors across timezones. Temporal's multiple types make the intent explicit in the type system.

Temporal.Instant represents a precise moment on the universal timeline — equivalent to a Unix timestamp but with nanosecond precision. It has no timezone or calendar — it's an absolute point in time. Ideal for logging events where you want a consistent reference point. To display it to a user, convert to ZonedDateTime: instant.toZonedDateTimeISO('Europe/London').