blog logo
iaman
KO

The Arrival of Temporal ( What's Wrong with Date )

TOC

Definition

Temporal means "of time, relating to time."

Background

1. Date handling is complicated 🤬

  • The existing Date API was based on Java's java.util.Date class, whose fundamental design was poor enough that Java replaced it in the early 2010s.
  • To preserve backward compatibility, JavaScript kept that class in the language as Date and went on using it.

2. Parsing behaves unreliably 😖

3. Date itself is mutable, which breeds bugs that are hard to trace 🐛

What Temporal improves

  1. Immutability

    const meeting = Temporal.PlainDateTime.from('2025-09-04T10:00')
const later = meeting.add({ hours: 2 })

console.log(meeting.toString()) // 2025-09-04T10:00:00 (the original is intact!)
console.log(later.toString())   // 2025-09-04T12:00:00 (a new object)

  2. Classes split by purpose

    ClassPurpose
    Temporal.PlainDateDate only (2025-03-16)
    Temporal.PlainTimeTime only (14:30:00)
    Temporal.PlainDateTimeDate + time (no time zone)
    Temporal.ZonedDateTimeDate + time + time zone
    Temporal.InstantAn absolute point in time, in UTC
    Temporal.DurationA span of time
    Temporal.NowCurrent-time utilities

  3. Full time zone support

    // Seoul time
const seoul = Temporal.Now.plainDateTimeISO('Asia/Seoul')

// New York time
const newYork = Temporal.Now.plainDateTimeISO('America/New_York')

  4. Nanosecond precision

    const now = Temporal.Now.instant()
// supports nanoseconds, not just milliseconds

Format

  • Every class uses an explicit format based on ISO 8601 / RFC 3339

    • 📌 ISO 8601 : the international standard format for expressing dates and times

    • 📌 RFC 3339 : a standard that extends ISO 8601 to express time zone information more clearly

      A date like 06/07/08 is read differently from country to country
US     : June 7, 2008
Europe : July 6, 2008
ISO 8601 : July 8, 2006 (YYYY-MM-DD)
=> using slashes ('2026/03/16') is not ISO 8601

  • An international standard that writes larger units first, then smaller ones

  • Designed so that sorting strings = sorting dates, which is why it's the standard across the development ecosystem

Three-line summary ✔️

  • Temporal comes from redesigning Date's bad design from scratch
  • The era when libraries like moment.js and date-fns are no longer needed is nearly here.
  • To use it today, you need a polyfill.

References