Temporal Mistakes

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;   // TypeError

Expecting 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).

Wrong

Temporal.Now.instant(); // not local time

Using PlainDate for Time

PlainDate has no time.

Wrong

Temporal.PlainDate.from("2026-05-17T14:30");

Forgetting Time Zone in ZonedDateTime

ZonedDateTime requires a time zone.

Wrong

Temporal.ZonedDateTime.from("2026-05-17T14:30:00");

Correct

Temporal.ZonedDateTime.from("2026-05-17T14:30:00+02:00[Europe/Oslo]");

Not Choosing the Right Type

Each Temporal type has a specific purpose.