Let's be honest: the built-in Date object in JavaScript has been a source of frustration for almost every developer who has ever touched the language. It's clunky, the months are zero-indexed for some inexplicable reason, and it's mutable, meaning if you change a date object in one part of your app, you might accidentally break it in another.

Think of the old Date object like a single, giant, smudge-prone whiteboard. You're trying to track your birthday, the current time in Tokyo, and a 30-minute meeting all on the same surface. If you try to erase and update the meeting time, you might accidentally smudge your birthday or shift the Tokyo time. It's one big, messy blob of "time" that tries to do everything at once.

The Temporal API is like replacing that whiteboard with a set of specialized, professional tools. Instead of one blob, you get a dedicated calendar for dates, a digital stopwatch for durations, and a world clock for time zones. Most importantly, these tools are immutable—once you create a date, it's written in ink. If you want to change it, you create a new one.

Picking the Right Tool for the Job

In the old days, you just had new Date(). With Temporal, you choose the object that actually fits your data. If you're building a birthday tracker, you don't need a time or a timezone; you just need a date. If you're building a pomodoro timer, you just need a duration.

// Just the date. No time, no timezone.
const birthday = Temporal.PlainDate.from('1992-05-15');

// Just the time. No date, no timezone.
const wakeUpTime = Temporal.PlainTime.from('07:00:00');

// The "everything" object. Date, time, and a specific timezone.
const meeting = Temporal.ZonedDateTime.from('2024-10-25T14:30[America/New_York]');


Notice how much cleaner that is? I don't have to worry about the system's local timezone messing up a "PlainDate" because a PlainDate simply doesn't have a timezone. It's just a calendar page.

Doing Math Without the Headache
One of the worst parts of the old Date object was adding time. You usually had to get the timestamp in milliseconds, add the milliseconds for a day, and then create a new date. It was a recipe for off-by-one errors.

Temporal introduces Temporal.Duration, which treats time spans as first-class citizens. You can add a duration to a date as easily as adding numbers.

const today = Temporal.Now.plainDateISO();
const twoWeeksLater = today.add({ days: 14 });

const tripDuration = Temporal.Duration.from({ days: 3, hours: 5 });
const departure = Temporal.Now.zonedDateTimeISO();
const arrival = departure.add(tripDuration);

console.log(`You'll arrive on ${arrival.toString()}`);


I love that the add() method returns a new object. The original today variable remains unchanged. This eliminates an entire category of bugs where a date was mutated deep inside a helper function and suddenly your UI is showing the wrong year.

Dealing with Timezones Properly
Timezones are the final boss of software engineering. The old Date object mostly relied on the user's local browser settings, which is a nightmare for global apps. Temporal handles this explicitly via ZonedDateTime.

If you need to know what time it is in London while your user is in Los Angeles, you don't have to do manual offset math (which fails during Daylight Savings transitions anyway). You just tell Temporal which timezone you want.

const laTime = Temporal.Now.zonedDateTimeISO('America/Los_Angeles');
const londonTime = laTime.withTimeZone('Europe/London');

console.log(`LA: ${laTime.toString()}`);
console.log(`London: ${londonTime.toString()}`);

📋 Practical Task

Build a Global Flight Arrival Calculator

You are building a tool for a travel agency. You need to create a function called calculateArrival that determines exactly when a flight lands in a different timezone.

Requirements:

• The function should take three arguments: departureTimeISO (a string like '2024-12-01T10:00'), departureTimeZone (e.g., 'America/New_York'), and flightDurationHours (a number).
• Use Temporal.ZonedDateTime.from to create the departure object.
• Use Temporal.Duration to create the flight length.
• Calculate the arrival time by adding the duration to the departure.
• Convert that arrival time to the destination timezone: 'Europe/London'.
• Return the final arrival time as a string using .toString().

Example Input: calculateArrival('2024-12-01T10:00', 'America/New_York', 7)
Expected Result: A string representing the arrival time in London (which should be 20:00 or 8 PM, accounting for the 5-hour time difference and 7-hour flight).