Typescript - Temporal

Temporal is the modern replacement for the problematic JavaScript Date object.

On this page

JavaScript’s Date object has been a source of frustration for decades. It’s mutable, doesn’t support non-Gregorian calendars well, and handling time zones is notoriously difficult.

The Temporal API is the modern solution, now stable in Deno since v2.7.

Why Temporal?

As Mat Marquis explains in his post, Date is essentially “broken” for modern web development:

  1. Mutability: Calling a method like setHours() on a Date object changes the original object, leading to subtle bugs.
  2. Parsing: Date.parse() is notoriously inconsistent across different browsers.
  3. Time Zones: Date only supports the user’s local time and UTC.

Temporal solves these problems by being immutable and providing specialized types for different use cases.

Getting Started

In Deno, Temporal is available globally. You don’t need to import anything.

Current Date and Time

The Temporal.Now object provides methods to get the current time in various formats:

// Current date (e.g., 2026-04-07)
const today = Temporal.Now.plainDateISO();


// Current date and time (e.g., 2026-04-07T12:14:30)
const now = Temporal.Now.plainDateTimeISO();


// Exact point in time (UTC)
const instant = Temporal.Now.instant();

Core Types

Temporal introduces several types to represent time more accurately:

PlainDate

Represents a date with no time or time zone (e.g., a birthday or a calendar event).

const birthday = Temporal.PlainDate.from("1995-12-07");
console.log(birthday.year); // 1995

PlainTime

Represents a time of day with no date or time zone (e.g., “the store opens at 9:00”).

const openingTime = Temporal.PlainTime.from("09:00:00");

ZonedDateTime

A complete date and time in a specific time zone. This is what you should use for most “real-world” events.

const meeting = Temporal.ZonedDateTime.from(
  "2026-03-15T14:30[America/New_York]"
);


// Convert to another time zone easily
const inTokyo = meeting.withTimeZone("Asia/Tokyo");

Manipulating Dates

One of Temporal’s best features is its immutable arithmetic. Methods like add and subtract return a new object.

const today = Temporal.Now.plainDateISO();
const nextWeek = today.add({ days: 7 });


console.log(today.toString());    // Still today
console.log(nextWeek.toString()); // Seven days from now

You can also use until and since to find the difference between two dates:

const start = Temporal.PlainDate.from("2026-01-01");
const end = Temporal.PlainDate.from("2026-04-07");


const diff = start.until(end, { largestUnit: "month" });
console.log(diff.months); // 3
console.log(diff.days);   // 6

Comparing Dates

Comparing dates is straightforward with the compare static method:

const d1 = Temporal.PlainDate.from("2026-01-01");
const d2 = Temporal.PlainDate.from("2026-02-01");


Temporal.PlainDate.compare(d1, d2); // -1 (d1 is before d2)

Tip All Temporal objects have an equals() method for simple equality checks.

Summary

Temporal makes working with dates and times in JavaScript (and Deno) predictable and robust.

  • Use PlainDate for calendar dates.
  • Use ZonedDateTime when time zones matter.
  • Always remember that Temporal objects are immutable.

For more examples, check out the Deno Temporal documentation.