Skip to content
timezoners

Handling Date and Time with JavaScript's New Temporal API

Simplify date logic, ditch timezone headaches, and write reliable code using JavaScript's powerful new Temporal API. —

Historically, working with dates and times in JavaScript meant wrestling with inconsistent timezone handling, confusing daylight saving time shifts, and unclear distinctions between local and global moments. The Temporal API aims to solve these long-standing issues by providing clearly defined and intuitive date-time primitives specifically designed for modern, timezone-aware applications.

The Temporal API introduces standardized date/time formats and clearly separates concepts such as wall-clock time, local time, and global instants. It helps you reason accurately about time by providing explicit representations of dates and times, preventing common mistakes.

Core Temporal API Concepts

Temporal provides specialized objects, each tailored to specific scenarios:

  • Temporal.Instant: A precise point on the universal timeline (UTC), unaffected by timezones.
  • Temporal.PlainDate: A calendar date without associated time or timezone.
  • Temporal.PlainTime: A clock time without an associated date or timezone.
  • Temporal.PlainDateTime: Combines date and time without timezone context.
  • Temporal.ZonedDateTime: Combines date, time, timezone, and a specific timezone offset.

Understanding ZonedDateTime

The Temporal.ZonedDateTime type combines a specific local date and time with explicit timezone information. Its format, such as "2025-03-15T23:00:00+09:00[Asia/Tokyo]", breaks down as follows:

  • 2025-03-15T23:00:00: The local date and time.
  • +09:00: The timezone offset from UTC (in this case, Tokyo is 9 hours ahead).
  • [Asia/Tokyo]: The named timezone, which includes daylight saving and historical timezone rules.

The offset (+09:00) indicates how far ahead or behind UTC the local time is, but alone, it doesn't capture daylight saving rules or historical timezone adjustments. The named timezone ([Asia/Tokyo]) provides additional context needed for accurate conversions and calculations.

Practical Examples

Creating Plain Dates

Representing a date without time:

const birthday = Temporal.PlainDate.from("1990-12-25");
console.log(
  `Year: ${birthday.year}, Month: ${birthday.month}, Day: ${birthday.day}`,
);
// Year: 1990, Month: 12, Day: 25

Working with Plain Times

Representing a wall-clock time without timezone:

const meetingTime = Temporal.PlainTime.from("09:30");
console.log(`Meeting starts at ${meetingTime.hour}:${meetingTime.minute}`);
// Meeting starts at 9:30

Merging Date and Time

Combining date and time into a single object:

const eventDateTime = birthday.toPlainDateTime(meetingTime);
console.log(eventDateTime.toString());
// "1990-12-25T09:30:00"

Accurate Timezone Handling with ZonedDateTime

Representing precise timezone-aware timestamps:

const conferenceCall = Temporal.ZonedDateTime.from(
  "2025-03-15T14:00:00[Europe/London]",
);
console.log(conferenceCall.toString());
// "2025-03-15T14:00:00+00:00[Europe/London]"

Converting Across Time Zones

Effortlessly converting between zones:

const tokyoTime = conferenceCall.withTimeZone("Asia/Tokyo");
console.log(tokyoTime.toString());
// "2025-03-15T23:00:00+09:00[Asia/Tokyo]"

Capturing Precise Global Moments with Instant

Creating exact, globally consistent timestamps:

const logTimestamp = Temporal.Now.instant();
console.log(logTimestamp.toString());
// e.g., "2025-03-15T14:00:00Z"

Calculating Durations

Easily determine intervals between times:

const departure = Temporal.PlainDateTime.from("2025-03-15T09:00");
const arrival = Temporal.PlainDateTime.from("2025-03-16T12:30");

const travelDuration = departure.until(arrival);
console.log(
  `Travel duration: ${travelDuration.days} days, ${travelDuration.hours} hours, ${travelDuration.minutes} minutes.`,
);
// Travel duration: 1 days, 3 hours, 30 minutes.

Simplifying Important Temporal Concepts

  • Local Time: Time perceived locally in a specific timezone.
  • Wall-Clock Time: Time shown on a clock face, independent of timezone.
  • UTC Instant: Precise moment in universal coordinated time, unaffected by local time differences.

Best Practices

  • Timezone-sensitive applications: Always use Temporal.ZonedDateTime.
  • Logging and audit trails: Rely on Temporal.Instant for global consistency.
  • Local events without timezone implications: Prefer PlainDate, PlainTime, or PlainDateTime.

Conclusion

The Temporal API streamlines date and time handling in JavaScript, clarifying previously confusing timezone and datetime logic. By adopting Temporal, your code becomes more predictable, maintainable, and accurate.

Back
Made with