Temporal Why

Why Was Temporal Created?

The Date object was created in 1995 and has some design issues that causes bugs.

For example, months in Date are zero-based, which is confusing.

Another problem is Date methods can change the Date object (mutation), which can create unexpected results.

Temporal was created to solve these issues with clearer object types and predictable behavior.

Examples

 // Month 5 is June

let d = new Date(2026, 5, 17);

A Simple Temporal Example

With Temporal, you can get today's date and add days in a clear and safe way.

Example

// Create a Temporal object

const today = Temporal.Now.plainDateISO();

// Add a duration

const nextWeek = today.add({ days: 7 });

Compare With Date

With JavaScript Date, you only have one type of date object.

Date Example

let d = new Date();

Separate Objects

Temporal gives you separate objects depending on what you need:

• Instant - Exact moment in UTC
• PlainDate - Date only
• PlainDateTime - Date and time only
• ZonedDateTime - Date and time with zone

When to Use Each Object

• Instant - For timestamps and comparisons
• PlainDate - For birthdays and calendar dates
• PlainDateTime - For local scheduling tasks
• ZonedDateTime - For time zone-aware apps

Temporal Objects are Immutable

Temporal objects are immutable, which means they cannot be changed after they are created.

Temporal objects return a new value instead of modifying the existing one.

Temporal Dates are DST-Safe

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.

Temporal Dates Uses RFC 5545

RFC 5545 (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.

JavaScript Date vs Temporal

Note: JavaScript Temporal is a set of built-in date and time objects that are easier and safer to use than JavaScript Date. Temporal uses distinct classes for dates and times to prevent bugs related to local time adjustments (like DST transitions).

When to Use Temporal?

Use Temporal when you need reliable date and time handling.

• You need correct time zone support
• You need safe date arithmetic (add / subtract, since / until)
• You need to avoid DST bugs
• You need predictable and readable code

Note: You may still have to use JavaScript Date to support environments where Temporal is not available.

Temporal Objects

Revised March 2026