JavaScript Temporal
What is JavaScript Temporal?
Temporal is the new standard for date and time in JavaScript.
New Temporal objects was designed to replace the old Date object.
Unlike legacy Date, Temporal objects are immutable and provide first-class support for time zones, daylight saving time (DST), date math and non-Gregorian calendars.
Temporal separates date and time into distinct classes to prevent "wall-clock" errors.
What Is Temporal?
Temporal is a built-in JavaScript API that provides date and time objects that are easier and safer to use than Date.
Temporal objects are immutable, which means they cannot be changed after they are created.
| Feature | Date | Temporal |
|---|---|---|
| Mutable (can change) | Yes | No |
| Time zone handling | Limited | Built-in |
| DST safe math | No | Yes |
| Modern API design | No | Yes |
Why Was Temporal Created?
The Date object was created in 1995 and has some design issues that still cause bugs today.
For example, months in Date are zero-based, which is confusing.
Example
let d = new Date(2026, 0, 17); // Month 0 = January
Another problem is that many Date methods change the same object (mutation), which can create unexpected results.
Example
let d = new Date();
d.setDate(d.getDate() + 7); // Changes the original object
Temporal was created to solve these issues with clearer object types and predictable behavior.
A Simple Temporal Example
With Temporal, you can get today's date and add days in a clear and safe way.
Example
let today = Temporal.Now.plainDateISO();
let nextWeek = today.add({ days: 7 });
Notice that today is not changed.
Temporal returns a new value instead of modifying the existing one.
DST-Safe Arithmetic
DST-safe arithmetic ensures time calculations (addition and subtraction) remain accurate across Daylight Saving Time (DST) transitions, preventing 1-hour errors.
It involves using timezone and calendar-aware objects (ZonedDateTime) that understand local clock shifts.
RFC 5545 iCalendar
RFC 5545, titled iCalendar (Internet Calendaring and Scheduling Core Object Specification), is the industry standard for exchanging calendar and scheduling information.
It allows different systems (like Google Calendar, Apple Calendar, and Microsoft Outlook) to communicate seamlessly.
When Should You Use Temporal?
Use Temporal when you need reliable date and time handling.
You need correct time zone support.
You want safe date arithmetic (add or subtract days, months, years).
You want to avoid DST bugs.
You want predictable and readable code.
You may still use Date for very simple tasks, or when you must support environments where Temporal is not available.
Temporal Object Types
Temporal includes several object types for different kinds of date and time values:
Temporal.Instant- An exact moment in time (UTC timestamp).Temporal.PlainDate- A date only (year, month, day).Temporal.PlainDateTime- Date and time without a time zone.Temporal.ZonedDateTime- Date and time with a time zone.Temporal.Duration- A length of time (days, hours, minutes).
In this tutorial, you will learn how each type works and when to use it.
Summary
Temporal is the modern way to work with dates and times in JavaScript.
Temporal fixes common Date problems like time zones, DST bugs, and confusing date math.
Next Chapter
Next, you will learn about Temporal vs Date and how Temporal objects work.
