Temporal: The Next Generation Date API in 2024

Working with dates in JavaScript sucks. The Temporal API introduces a new global object, designed to simplify date and time manipulations in JavaScript. Its primary objectives include easing the handling of dates and times, providing enhanced support for scenarios involving dates without times, times without dates, and time zones.

Temporal API Data Types

The API presents various data types, each addressing specific date-related concerns. The distinction between plain and zoned versions is notable, with plain denoting date/time devoid of timezone information, while zoned versions carry timezone specifics.

1 — PlainDateTime

A straightforward object representing date and time without timezone information. Creating a new instance can be achieved using methods like Temporal.Now.plainDateTimeISO() or the constructor.

const today = Temporal.Now.plainDateTimeISO()
console.log(today.toString()) // 2024-03-01T20:07:29.431049411

2 — PlainDate

Perfect for representing a date without any associated time or timezone. Creation methods include Temporal.Now.plainDateISO() and Temporal.PlainDate.from().

const today = Temporal.Now.plainDateISO();
console.log(today.toString()); 
// 2024-03-01

const persian = Temporal.Now.plainDate("persian");
console.log(persian.toString());
// 2024-03-01[u-ca=persian]

const date1 = Temporal.PlainDate.from("2024-03-01");
console.log(date1.toString());
// 2024-03-01

const date2 = Temporal.PlainDate.from({ year: 2024, month: 3, day: 1 });
console.log(date2.toString());
// 2024-03-01

3 — PlainTime

Represents time without a date or timezone. Notably, there is no Temporal.Now.plainTime function; creation is possible through methods like Temporal.Now.plainTimeISO() or Temporal.PlainTime.from().

const today = Temporal.Now.plainTimeISO();
console.log(today.toString());
// 20:29:49.244389237

const time1 = Temporal.PlainTime.from("20:29:17");
console.log(time1.toString());
// 20:29:17

const time2 = Temporal.PlainTime.from({ hour: 20, minute: 29, second: 17 });
console.log(time2.toString());
// 20:29:17

4 — ZonedDateTime

A comprehensive datetime object including timezone details, crucial for local date/time representation and calculations considering factors like daylight saving time.

const today = Temporal.Now.zonedDateTimeISO();
console.log(today.toString());
// 2024-03-01T20:35:42.372742365+03:30[Asia/Tehran]

const persian = Temporal.Now.zonedDateTime("persian");
console.log(persian.toString());
// 2024-03-01T20:35:42.376742372+03:30[Asia/Tehran][u-ca=persian]

const date1 = Temporal.ZonedDateTime.from({
  timeZone: "Asia/Tehran",
  calendar: "persian",
  year: 1402,
  month: 12,
  day: 11,
});
console.log(date1.toString());
// 2024-03-01T00:00:00+03:30[Asia/Tehran][u-ca=persian]

5 — Instance

Similar to ZonedDateTime but always in UTC, disregarding any specific calendar. Creation and manipulation methods differ, ensuring accurate representation.

const today = Temporal.Now.instant();
console.log(today.toString());
// 2024-03-01T17:13:58.49823849Z

const date = Temporal.Instant.from("2024-03-01T20:38Z");
console.log(date.toString());
// 2024-03-01T20:38:00Z

6 — PlainMonthDay

Ideal for occasions like holidays, representing a day and month without the year.

const date1 = Temporal.PlainMonthDay.from("03-01");
console.log(date1.toString());
// 03-01
const date2 = Temporal.PlainMonthDay.from({ month: 3, day: 1 });
console.log(date2.toString());
// 03-01

7 — PlainYearMonth

Similar to PlainMonthDay but excluding day information, suitable for events within a month.

const date1 = Temporal.PlainYearMonth.from("2024-03");
console.log(date1.toString());
// 2024-03
const date2 = Temporal.PlainYearMonth.from({ year: 2024, month: 3 });
console.log(date2.toString());
// 2024-03

Helper Methods

1 — add and subtract

Simplifying date manipulation by adding or subtracting specific durations.

const today = Temporal.Now.plainDateISO();
console.log(today.add({ days: 4, months: 2 }).toString());
// 2024-05-05

2 — since and until

Calculating the temporal distance between two dates with customizable units.

const today = Temporal.Now.plainDateISO();
const yesterday = today.subtract({ days: 1 });
console.log(today.since(yesterday).toString());
// P1D

3 — equals

Ensuring accurate equality comparison between temporal date objects.

const today = Temporal.Now.plainDateISO();
const today2 = Temporal.Now.plainDateISO();
console.log(today === today2);
// false
console.log(today.equals(today2));
// true

4 — with

Overwriting specific fields on a date object, allowing for easy modifications.

const today = Temporal.Now.plainDateISO()
console.log(today.with({ year: 2024, month: 3 }).toString())
// 2024-03-21

5 — round

Rounding a temporal date to a specific unit for precise calculations.

const today = Temporal.Now.plainDateTimeISO()
console.log(today.round("hour").toString())
// 2024-03-01T21:00:00

If you want to modify how the rounding is performed you can instead pass an object that takes smallestUnit, roundingIncrement, and roundingMode.

const today = Temporal.Now.plainDateTimeISO();
console.log(today.round({ smallestUnit: "hour" }).toString());
// 2024-03-01T21:00:00
console.log(
today.round({ smallestUnit: "hour", roundingMode: "ceil" }).toString()
);
// 2024-03-01T21:00:00
console.log(
  today.round({ smallestUnit: "hour", roundingIncrement: 6 }).toString()
);
// 2024-03-01T18:00:00

6 — compare

Facilitating date sorting by comparing date objects.

const today = Temporal.Now.plainDateISO();
const yesterday = today.subtract({ days: 1 });
const tomorrow = today.add({ days: 1 });
console.log(
  [today, yesterday, tomorrow]
    .sort(Temporal.PlainDate.compare)
    .map((item) => item.toString())
);
// ['2024-02-29', '2024-03-01', '2024-03-02']

Beyond the Basics

Other Data Types

• Duration: Representing a span of time, offering methods like add, subtract, and with for manipulation.
• TimeZone: Capturing specific timezone information, crucial for accurate date and time representation.
• Calendar: Although less frequently used, it can be created using the from method, encapsulating calendar-specific details.

A Glimpse into the Future

Now hopefully after reading all this, you are excited to start trying out the temporal API. The only bad news I have is that this API is not yet available as it is still in proposal stage 3. There are currently no browsers with any support for this API, but you can use a polyfill if you want to start using this API today.

Get iman malekian’s stories in your inbox

Join Medium for free to get updates from this writer.

Remember me for faster sign in

There are multiple polyfills available for this API, but I found the @js-temporal/polyfill to be a good one. Once you install this library you can start using the temporal API immediately.

Conclusion

Dates in JavaScript suck, but with the introduction of the temporal API working with dates will be something you can actually enjoy doing.