Temporal

Table of Contents

Introduction

Date has been a long-standing pain point in ECMAScript. This is a proposal for Temporal, a global Object that acts as a top-level namespace (like Math), that brings a modern date/time API to the ECMAScript language. For a detailed look at some of the problems with Date, and the motivations for Temporal, see: Fixing JavaScript Date.

Temporal fixes these problems by:

Cookbook

A cookbook to help you get started and learn the ins and outs of Temporal is available here.

API Documentation

Temporal.now

See Temporal.now Documentation for detailed documentation.

Temporal.Instant

A Temporal.Instant represents a fixed point in time (called "exact time"), without regard to calendar or location. For a human-readable local calendar date or clock time, use a Temporal.TimeZone and Temporal.Calendar to obtain a Temporal.ZonedDateTime or Temporal.DateTime.

See Temporal.Instant Documentation for detailed documentation.

Temporal.ZonedDateTime

NOTE: this type is not checked into the polyfill yet, but is planned to land in late October 2020.

A Temporal.ZonedDateTime is a timezone-aware, calendar-aware date/time type that represents a real event that has happened (or will happen) at a particular exact time from the perspective of a particular region on Earth. This type is optimized for use cases that require a time zone, including DST-safe arithmetic and interoperability with RFC 5545 (iCalendar).

As the broadest Temporal type, Temporal.ZonedDateTime can be considered a combination of Temporal.TimeZone, Temporal.Instant, and Temporal.DateTime (which includes Temporal.Calendar).

See Temporal.ZonedDateTime Documentation for detailed documentation.

Temporal.Date

A Temporal.Date object represents a calendar date that is not associated with a particular time or time zone.

This can also be converted to partial dates such as Temporal.YearMonth and Temporal.MonthDay.

See Temporal.Date Documentation for detailed documentation.

Time Zones and Resolving Ambiguity

Converting between wall-clock/calendar-date types (like Temporal.Date, Temporal.Time, and Temporal.DateTime) and exact time types (Temporal.Instant and Temporal.ZonedDateTime) can be ambiguous because of time zones and daylight saving time.

Read more about handling time zones, DST, and ambiguity in Temporal.

Temporal.Time

A Temporal.Time object represents a wall-clock time that is not associated with a particular date or time zone.

See Temporal.Time Documentation for detailed documentation.

Temporal.DateTime

A Temporal.DateTime represents a calendar date and wall-clock time that does not carry time zone information. It can be converted to a Temporal.ZonedDateTime or a Temporal.Instant using a Temporal.TimeZone. For use cases that require a time zone, especially using arithmetic or other derived values, consider using Temporal.ZonedDateTime instead because that type automatically adjusts for Daylight Saving Time.

See Temporal.DateTime Documentation for detailed documentation.

Temporal.YearMonth

A date without a day component. This is useful to express things like "the November 2010 meeting".

See Temporal.YearMonth Documentation for detailed documentation.

Temporal.MonthDay

A date without a year component. This is useful to express things like "Bastille Day is on the 14th of July".

See Temporal.MonthDay Documentation for detailed documentation.

Temporal.Duration

A Temporal.Duration expresses a length of time. This is used for date/time arithmetic and for measuring differences between Temporal objects.

See Temporal.Duration Documentation for detailed documentation.

Balancing

Unlike the other Temporal types, the units in Temporal.Duration don't naturally wrap around to 0: you may want to have a duration of "90 minutes," and you don't want it to unexpectedly turn into "1 hour and 30 minutes."

See Duration balancing for more on this topic.

Temporal.TimeZone

A Temporal.TimeZone represents an IANA time zone, a specific UTC offset, or UTC itself. Because of this Temporal.TimeZone can be used to convert between Temporal.Instant and Temporal.DateTime as well as finding out the offset at a specific Temporal.Instant.

See Temporal.TimeZone Documentation for detailed documentation. A conceptual explanation of handling time zones, DST, and ambiguity in Temporal is also available.

Temporal.Calendar

A Temporal.Calendar represents a calendar system. Most code will use the ISO 8601 calendar, but other calendar systems are available.

See Temporal.Calendar Documentation for detailed documentation.

Other Documentation

Key Concepts

Design drafts

Obsolete Pages

Object Relationship