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:
Temporal fixes these problems by:
A cookbook to help you get started and learn the ins and outs of Temporal is available here.
Temporal.now.instant()- get the exact time since Unix epoch
Temporal.now.timeZone()- get the current system time zone
Temporal.now.zonedDateTime(calendar)- get the current date and wall-clock time in the system time zone and specified calendar
Temporal.now.zonedDateTimeISO()- get the current date and wall-clock time in the system time zone and ISO-8601 calendar
Temporal.now.date(calendar)- get the current date in the system time zone and specified calendar
Temporal.now.dateISO()- get the current date in the system time zone and ISO-8601 calendar
Temporal.now.time(calendar)- get the current wall-clock time in the system time zone and specified calendar
Temporal.now.timeISO()- get the current wall-clock time in the system time zone and ISO-8601 calendar
Temporal.now.dateTime(calendar)- get the current system date/time in the system time zone, but return an object that doesn't remember its time zone so should NOT be used to derive other values (e.g. 12 hours later) in time zones that use Daylight Saving Time (DST).
Temporal.now.dateTimeISO()- same as above, but return the DateTime in the ISO-8601 calendar
See Temporal.now Documentation for detailed documentation.
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.Calendar to obtain a
See Temporal.Instant Documentation for detailed documentation.
NOTE: this type is not checked into the polyfill yet, but is planned to land in late October 2020.
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.ZonedDateTime can be considered a combination of
Temporal.DateTime (which includes
See Temporal.ZonedDateTime Documentation for detailed documentation.
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
See Temporal.Date Documentation for detailed documentation.
Converting between wall-clock/calendar-date types (like
Temporal.DateTime) and exact time types (
Temporal.ZonedDateTime) can be ambiguous because of time zones and daylight saving time.
Read more about handling time zones, DST, and ambiguity in
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 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
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.
A date without a day component. This is useful to express things like "the November 2010 meeting".
See Temporal.YearMonth Documentation for detailed documentation.
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 expresses a length of time.
This is used for date/time arithmetic and for measuring differences between
See Temporal.Duration Documentation for detailed documentation.
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 represents an IANA time zone, a specific UTC offset, or UTC itself.
Because of this
Temporal.TimeZone can be used to convert between
Temporal.DateTime as well as finding out the offset at a specific
See Temporal.TimeZone Documentation for detailed documentation. A conceptual explanation of handling time zones, DST, and ambiguity in Temporal is also available.
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.
Temporal.Durationunits wrap around to 0 and when they don't.
Temporal.parseAPI, which is not currently planned to be implemented.
Temporal.ZonedDateTimewhich is a new type combining an exact time with a time zone and calendar, and exposing a superset of the
Temporal.DateTimeAPI. Superseded by the documentation, but contains background info about the reasons and goals behind this type.