Temporal is a powerful API, but it can be confusing at first.
- Remember to use the correct Temporal type
- Avoid implicit conversions
- Always handle time zones correctly
- Use compare() instead of < and >
- Remember that Temporal Objects are immutable
Here are some common mistakes and how to avoid them.
Missing UTC (Z) for Instant
An Instant must always include UTC.
Wrong
const instant = Temporal.Instant.from("2026-05-17T14:30:00");Using PlainDateTime with Time Zone
PlainDateTime does not support time zones.
Wrong
const date = Temporal.PlainDateTime.from("2026-05-17T14:30:00Z");Comparing Different Types
Temporals can go wrong when comparing different types.
Wrong
const d1 = Temporal.PlainDate.from("2026-05-17");
const d2 = Temporal.Instant.from("2026-05-17T14:30Z");
Temporal.PlainDate.compare(d1, d2);Correct
const d1 = Temporal.PlainDate.from("2026-05-17");
const d2 = Temporal.PlainDateTime.from("2026-05-17T14:30");
Temporal.PlainDate.compare(d1, d2);Using equals() with Different Types
Temporals can go wrong when comparing different types.
Wrong
const d1 = Temporal.PlainDate.from("2026-05-17");
const d2 = Temporal.Instant.from("2026-05-17T14:30Z");
d1.equals(d2);Correct
const d1 = Temporal.PlainDate.from("2026-05-17");
const d2 = Temporal.PlainDateTime.from("2026-05-17T14:30");
d1.equals(d2.toPlainDate());Using ==, < or > for Comparison
Temporal objects cannot be compared with ==, ===, < or >.
Wrong
const d1 = Temporal.PlainDate.from("2026-05-17");
const d2 = Temporal.PlainDate.from("2026-05-17");
d1 === d2; // False
d1 == d2; // False
d1 < d2; // TypeError
d1 > d2; // TypeErrorExpecting Mutation
Temporal objects are immutable.
Wrong
const date = Temporal.PlainDate.from("2026-05-17");
date.add({ months: 1 });Using valueOf()
Temporal objects do not convert to numbers.
Example
const date = Temporal.PlainDate.from("2026-05-17");
try {
text = date.valueOf();
} catch (err) {
text = err.name;
}Using Instant for Local Time
Instant is always UTC (not local time).
Temporal.Now.instant(); // not local timeUsing PlainDate for Time
PlainDate has no time.
Temporal.PlainDate.from("2026-05-17T14:30");Forgetting Time Zone in ZonedDateTime
ZonedDateTime requires a time zone.
Temporal.ZonedDateTime.from("2026-05-17T14:30:00");Temporal.ZonedDateTime.from("2026-05-17T14:30:00+02:00[Europe/Oslo]");Not Choosing the Right Type
Each Temporal type has a specific purpose.
| Type | Use |
|---|---|
| Instant | Exact moment (UTC) |
| PlainDate | Date only |
| PlainTime | Time only |
| PlainDateTime | Date + time only |
| ZonedDateTime | Date + time + time zone |
| Duration | Length of time only |