CodePark/ questions / Dates & time zones
START PRACTICINGPRACTICE
Frontend question · Internationalization › Dates & time zones

What is Temporal, and what problems with Date does it fix?

const meeting = Temporal.ZonedDateTime.from(
  "2024-03-09T12:00[America/New_York]"
);
meeting.add({ days: 1 }).toString();
// "2024-03-10T12:00:00-04:00[America/New_York]"

Temporal.PlainDate.from("1990-05-20"); // a date with no time or zone

Temporal is the new built-in date and time API in JavaScript. It replaces Date, which has many design problems.

Problems with Date:

  • It is mutable. setDate changes the object, so shared dates change by surprise.
  • Months start at 0, so new Date(2024, 2, 9) is 9 March.
  • It only knows UTC and the computer's local time zone. It can't do math in any other zone.
  • It has no type for "just a date" or "just a time", so a birthday becomes a moment that shifts by time zone.
  • Parsing strings is inconsistent.

What Temporal gives you:

  • Immutable objects. Every method returns a new value.
  • Separate types for separate ideas:

Instant is an exact moment. ZonedDateTime is a moment in a named zone. PlainDate, PlainTime and PlainDateTime have no zone. Duration is a length of time.

  • Correct calendar math across daylight saving changes. In the code, adding one day keeps 12:00 even though that day has 23 hours.
  • Support for any IANA time zone and for non-Gregorian calendars.
  • Months start at 1.

Browser support arrived in 2025 and 2026, starting with Firefox. Check MDN for current support, and use a polyfill such as @js-temporal/polyfill where it is missing.

  • Temporal is the new built-in date and time API that replaces Date.
  • Date is mutable, uses 0-based months and only knows UTC and the local zone.
  • Temporal objects are immutable.
  • It has separate types like Instant, ZonedDateTime and PlainDate.
  • It does correct calendar math across daylight saving changes in any time zone.
  • Support is still new, so check it and use a polyfill if needed.