JS Temporal Dates

Temporal Intro

Temporal is a modern date and time API designed to replace the legacy Date object. It provides clearer types (date-only, time-only, date-time), safer arithmetic, and first-class time zone support.

Availability note: Temporal is still not supported in all widely-used browsers, so you should check compatibility before using it in production.

// Feature detection (browser support varies)
if (typeof Temporal !== "undefined") {
  console.log("Temporal is available");
} else {
  console.log("Temporal is not available (use Date or a polyfill)");
}

Temporal is designed as a full replacement for Date and is documented by TC39 and MDN.

Temporal vs Date

The legacy Date API is mutable and mixes multiple concepts (date, time, and time zone behavior) in one object. Temporal provides separate immutable types for different use cases, which helps avoid bugs.

// Date is mutable
const d = new Date(2025, 0, 1);
d.setDate(d.getDate() + 1);
console.log(d.toDateString());

// Temporal types are immutable (examples assume Temporal is available)
const plain = Temporal.PlainDate.from("2025-01-01");
const tomorrow = plain.add({ days: 1 });
console.log(plain.toString());
console.log(tomorrow.toString());

Rule of thumb:

• Use Temporal.PlainDate for date-only values (birthdays, deadlines, schedules).
• Use Temporal.Instant for exact timestamps (logging, events).
• Use Temporal.ZonedDateTime when a time zone matters (appointments in a specific city).

Temporal PlainDate

Temporal.PlainDate represents a calendar date without a time or time zone. This is one of the biggest improvements over Date for everyday business data.

const a = Temporal.PlainDate.from("2026-02-13");

console.log(a.year);  // 2026
console.log(a.month); // 2
console.log(a.day);   // 13

// Create with fields
const b = new Temporal.PlainDate(2026, 2, 13);
console.log(b.toString());

Comparisons are explicit and predictable.

const x = Temporal.PlainDate.from("2026-02-01");
const y = Temporal.PlainDate.from("2026-02-13");

console.log(Temporal.PlainDate.compare(x, y)); // -1 (x < y)

Temporal Math

Temporal provides clean date arithmetic with add() and subtract(). Unlike Date math, you don’t mutate the original value.

const start = Temporal.PlainDate.from("2026-02-13");

const plus7 = start.add({ days: 7 });
const minus1Month = start.subtract({ months: 1 });

console.log(start.toString());      // 2026-02-13
console.log(plus7.toString());      // 2026-02-20
console.log(minus1Month.toString()); // 2026-01-13

You can also calculate differences between two dates using until() or since().

const from = Temporal.PlainDate.from("2026-02-01");
const to = Temporal.PlainDate.from("2026-02-13");

const diff = from.until(to);
console.log(diff.days); // 12

Practical Adoption Note

Because support is still limited across browsers, common approaches are:

• Use feature detection and fallback to Date for unsupported browsers.
• Use a polyfill if your project setup allows it.

See the Temporal docs for the full API surface and compatibility details.