JavaScript Temporal vs Date
Compare JavaScript Date with Temporal
Learn the differences in:
- Mutation
- Time zones
- DST handling
- Date math
Learn why Temporal is the modern alternative to Date
JavaScript Date Problems
The JavaScript Date object is old and has several design problems.
These problems can lead to bugs in with time zones, DTS (daylight saving time), and date math.
Common Date Mistakes
These are the most common mistakes developers make when using Date objects:
Using the wrong month number because months start at 0.
Accidentally changing a date object by calling a mutating method.
Parsing unclear strings that behave differently across environments.
Mixing local time and UTC values in the same program.
Doing math across DST changes and getting unexpected hours.
Note
The JavaScript Date object has been used since 1995.
Temporal is the modern replacement designed to fix many of Date's problems.
Date Objects are Mutable
Date objects can change. They are mutable.
Many Date methods change the same object.
This can create unexpected results when the same Date value is reused.
Date Example
// Create a Date
let d = new Date(2026, 5, 17);
let x = d;
// Add 7 days to d (and same)
d.setDate(d.getDate() + 7);
// Here the original d is gone and x have changed
Try it Yourself »
Note
In the example above, the variables d and x point to the same object.
So x changes when d changes.
Temporal Objects are Immutable
Temporal objects cannot change. They are immutable.
Operations return a new value instead.
Temporal Example
// Create a Date
let d = Temporal.PlainDate.from("2026-05-17");
// Add 7 days
let next = d.add({ days: 7 });
// Here original date is kept
Try it Yourself »
Date and Time Zone
new Date(2026, 4, 1) creates a timestamp of your local time zone at midnight.
This means a day can "shift" when you format it in UTC or in another zone.
Example
// Months are 0-based (4 = May)
const d = new Date(2026, 4, 1);
// Might be 2026-04-30T22:00:00.000Z in some time zones:
d.toISOString();
Try it Yourself »
Local Time vs UTC Is Confusing
The Date object mixes local time and UTC.
A Date object always stores a timestamp, but it can display values as local time or UTC.
This mix can easily cause confusion when converting and comparing dates.
The same moment can look different depending on how it is displayed.
Date Example
let d = new Date();
let time1 = d.toString();
let time2 = d.toUTCString();
Try it Yourself »
Temporal ZonedDateTime
Temporal uses clear types for time zones.
ZonedDateTime always includes a time zone.
Date Parsing is Inconsistent
new Date("2026-05-01") parses as an instant as UTC in modern JS,
but historically it has been a minefield of different formats, browser quirks and locale surprises.
Some date strings are parsed differently across browsers and environments.
Different formats may be interpreted as local time or UTC, which can change the result.
Example
let a = new Date("2026-05-17");
let b = new Date("05/17/2026");
let c = new Date("17/05/2026");
Try it Yourself »
Temporal PlainDate
Temporal avoids the problems above by:
- defining strict parsing rules for ISO strings
- using Temporal.Instant.from() for clearly-typed conversions
Temporal.PlainDate is not a timestamp.
It is just "2026-05-01" with no time and no time zone, so there can not be any shifting.
It is safer to avoid unclear formats and use explicit formats when possible.
Date Months Start at 0
In the JavaScript Date object, months are zero-based.
That means January is month 0, and December is month 11.
Note
The Date object is confusing because most people expect January to be month 1.
Temporal Months are 1-Based
In the JavaScript Temporal object, January is month 1.
This is much more user friendly
DST Can Break Date Math
Daylight saving time (DST) can cause a day to be 23 or 25 hours long.
This can break calculations that assume every day is exactly 24 hours.
Example
let start = new Date("2026-03-29T00:00:00");
let end = new Date(start.getTime() + 24 * 60 * 60 * 1000);
The result can be off by one hour in time zones with DST changes.
Date Math
Date math with Date often requires manual calculations.
Date Example
let start = new Date("2026-05-17");
start.setDate(start.getDate() + 30);
Try it Yourself »
Temporal has built-in date arithmetic.
Temporal Example
let start = Temporal.PlainDate.from("2026-05-17");
let result = start.add({ days: 30 });
Try it Yourself »
Nanosecond Precision
Unlike the Date object which uses milliseconds, Temporal.Instant offers 1 million times higher nanosecond precision.
Clear Separation of Types
The Date object represents both a date and a time in one object.
Temporal objects separates different use cases into different objects.
| Object | Description |
|---|---|
| Temporal.Duration | Length of time (days, hours, minutes) |
| Temporal.Instant | Exact moment in time (UTC timestamp) |
| Temporal.PlainDate | Plain date only (year, month, day) |
| Temporal.PlainTime | Plain time only |
| Temporal.PlainYearMonth | Plain year and month only |
| Temporal.PlainMonthDay | Plain month and day only |
| Temporal.PlainDateTime | Date and time without a time zone |
| Temporal.ZonedDateTime | Date and time with a time zone |
| Temporal.Now | Current time (UTC timestamp) |
This makes code easier to read and less error-prone.
Differences Between Date and Temporal
| Feature | Date | Temporal |
|---|---|---|
| Created | 1995 | 2026 |
| Time zone support | Limited | Built-in |
| Immutable | No | Yes |
| Date-Only Type | No | Yes |
| Time-Only Type | No | Yes |
| 1-Based Months | No | Yes |
| DST safe arithmetic | No | Yes |
| RFC 5545 iCalendar | No | Yes |
| Modern API design | No | Yes |
| Precisition | Milliseconds | Nanoseconds |
When to Use Date?
You may still use Date for simple tasks such as getting a quick timestamp.
You may also need it if you support older environments without Temporal.
When to Use Temporal?
You need correct time zone handling.
You work with international users.
You want safe date arithmetic.
You want clear and modern code.
Date works, but it has limitations and confusing behavior.
Temporal is safer, clearer, and designed for modern applications.
