Dates and Temporal

This chapter follows Regular expressions in JavaScript.

JavaScript time handling splits between the legacy Date object and the Temporal proposal (stage 4, shipping in modern engines behind flags or progressively enabled).

Date today

Date stores a single UTC timestamp (milliseconds since epoch). Many methods mutate the instance.

1
const d = new Date("2026-11-01T12:00:00Z");
2
d.getUTCFullYear(); // 2026
3
d.setMonth(10); // mutates in local timezone interpretation
4
d.toISOString(); // UTC string

Strength	Limitation
Universal support	Month/day APIs use local timezone by default
`Date.now()` for timestamps	No first-class time zone or calendar type
ISO strings in JSON logs	Parsing `YYYY-MM-DD` is implementation-sensitive
	Arithmetic via `setHours` is easy to get wrong

For display in a user locale, pair Date with Intl.DateTimeFormat rather than manual string assembly.

Temporal direction

Temporal models civil dates, wall-clock times, durations, and time zones as immutable values with explicit types:

Type	Role
`Temporal.Instant`	Exact point on UTC timeline
`Temporal.ZonedDateTime`	Instant + time zone + calendar
`Temporal.PlainDate`	Calendar date without time zone
`PlainTime`, `PlainDateTime`	Wall clock without zone
`Temporal.Duration`	Elapsed amount
`Temporal.TimeZone`, `Temporal.Calendar`	Named zone and calendar rules

1
// API shape (when Temporal is available)
2
const plain = Temporal.PlainDate.from("2026-11-01");
3
plain.add({ days: 1 }); // new PlainDate, plain unchanged
4

5
const zoned = Temporal.ZonedDateTime.from(
6
  "2026-11-01T09:00[Europe/Berlin]"
7
);
8
zoned.toInstant(); // unambiguous UTC instant

Design goals Temporal addresses:

No mutable set* methods on shared instances.
Explicit time zone and calendar instead of implicit local-only behavior.
Safe arithmetic (add, until, round) with clear units.
Interchange formats aligned with ISO 8601 and iCal.

Status comparison

	`Date`	`Temporal`
Standard	ES since 1st edition	ES2024+ / ongoing rollout
Engine support	Everywhere	Chrome, Node (recent), others catching up—check `globalThis.Temporal`
npm polyfill	Rarely needed	`@js-temporal/polyfill` for older runtimes
JSON	ISO strings common	Serialize to string; parse with `Temporal.*.from`
Intl integration	Format via Intl	Designed to work with Intl calendars and time zones

Practical guidance:

Shipped libraries targeting all LTS Node versions: stay on Date + Intl, or use Temporal polyfill with a documented bundle cost.
Greenfield browser apps on current channels: feature-detect Temporal and fall back to Date or polyfill.
Store and transmit: prefer UTC instants (Instant or Date.toISOString()) plus a named IANA zone when you need local scheduling.

Continue with Internationalization with Intl.