Decoding JavaScript Dates: Why They Break and How Temporal Fixes It

Overview

Time, as a human concept, seems straightforward. But in the world of software, it's notoriously tricky. JavaScript's built-in Date object has been a source of confusion and bugs for years. This tutorial dives deep into why date and time handling in JavaScript is so problematic, how the Temporal proposal aims to solve these issues, and what you need to know to start using Temporal. Whether you're a seasoned developer or just starting out, understanding these concepts will save you from subtle, hard-to-find bugs.

Prerequisites

• Basic knowledge of JavaScript (variables, functions, objects)
• Familiarity with asynchronous programming (optional but helpful)
• Node.js v14+ or a modern browser for testing Temporal (polyfill available)

Step-by-Step Instructions

1. Identify Common JavaScript Date Pitfalls

Before we can appreciate Temporal, we must understand what's broken with the Date object. Key issues include:

• Mutable state – Methods like setMonth() mutate the original object, leading to accidental side effects.
• Time zone confusion – The Date object only stores UTC internally, but most methods operate in local time, causing unexpected conversions.
• Poor arithmetic – Adding days or months can produce bizarre results (e.g., adding one month to January 31 gives March 3).
• Lack of calendar support – No built-in support for non-Gregorian calendars or time zones beyond UTC/local.

For example, the following code snippet shows months appearing in a different order than expected due to time zone offset:

const date = new Date('2024-01-01T00:00:00Z');
console.log(date.getMonth()); // 0 (January) in UTC, but might be December 31 in other timezones

2. Explore the Temporal Proposal

Temporal is a stage 3 proposal (near final) that brings robust date and time handling to JavaScript. It introduces several types:

• Temporal.Instant – A single point in time (UTC timestamp).
• Temporal.PlainDate – A calendar date without time or time zone.
• Temporal.PlainTime – A wall-clock time without date or time zone.
• Temporal.PlainDateTime – A date and time without time zone.
• Temporal.ZonedDateTime – A date and time with a specific time zone.
• Temporal.Duration – A length of time (hours, days, etc.).
• Temporal.TimeZone – Represents an IANA time zone.
• Temporal.Calendar – Represents a calendar system (Gregorian, Islamic, etc.).

3. Install and Use Temporal (Polyfill)

Since Temporal is not yet natively supported, use a polyfill. For Node.js:

npm install @js-temporal/polyfill

Then in your code:

const { Temporal } = require('@js-temporal/polyfill');
// Now use Temporal classes

For browsers, include a script tag or use a bundler.

4. Create and Manipulate Dates with Temporal

Let's compare doing a simple task – adding a month – with Date vs Temporal.

With Date (buggy):

const date = new Date('2024-01-31');
date.setMonth(date.getMonth() + 1);
console.log(date); // March 3, 2024 (because Feb 31 doesn't exist)

With Temporal (correct):

let plainDate = Temporal.PlainDate.from('2024-01-31');
plainDate = plainDate.add({ months: 1 });
console.log(plainDate.toString()); // 2024-02-29 (auto-constrains to leap year)

Notice Temporal returns a new object; it's immutable. Overflow handling is predictable: it can constrain, reject, or balance (default is constrain).

5. Work with Time Zones

Time zones are a nightmare with Date. Temporal makes them first-class.

// Create a zoned datetime for New York
const zdt = Temporal.ZonedDateTime.from({
  timeZone: 'America/New_York',
  year: 2024,
  month: 3,
  day: 10,
  hour: 2 // This hour might be skipped due to DST
});
console.log(zdt.toString()); // 2024-03-10T03:00:00-04:00[America/New_York] (auto-adjusted)

You can convert to UTC easily:

const instant = zdt.toInstant();
console.log(instant.epochMilliseconds);

6. Perform Date Arithmetic and Comparisons

Temporal supports add, subtract, and comparison operators via methods like equals, since, and until.

const start = Temporal.PlainDate.from('2024-01-01');
const end = Temporal.PlainDate.from('2024-12-31');
const duration = start.until(end);
console.log(duration.toString()); // P364D (duration of 364 days, not including end)

// Compare
console.log(start.equals(end)); // false
console.log(start.since(end).sign); // -1 (start is before end)

7. Round and Truncate Durations

Temporal offers precise rounding:

const dur = Temporal.Duration.from({ hours: 2, minutes: 45 });
console.log(dur.round({ smallestUnit: 'hours' }).toString()); // PT3H

Common Mistakes

• Using Date.prototype methods on Temporal objects – They are different APIs; Temporal objects have no relationship with Date.
• Assuming Temporal interprets strings the same as Date – Temporal uses ISO 8601 rigorously; invalid strings throw errors.
• Forgetting that PlainDate has no time zone – Do not use PlainDate to represent events that depend on local time.
• Not handling DST transitions – Temporal's ZonedDateTime automatically adjusts, but you should be aware of skipped/repeated times.
• Mutating objects when you intended immutability – Temporal objects are immutable; always assign the result of add, with, etc.

Summary

JavaScript's Date object is fundamentally flawed in its mutability, time zone handling, and arithmetic. The Temporal proposal provides a clean, immutable, and comprehensive API for dates, times, time zones, and durations. By using Temporal, you avoid common date-related bugs and gain powerful features like time zone conversion, calendar support, and precise math. Start adopting Temporal today with the polyfill, and future-proof your applications.