Provides standard objects and functions for working with dates and times.
NOTE: The current working version is the Polyfill. Specification text is being written based on that!
- Maggie Pint (@maggiepint)
- Philipp Dunkel (@pipobscure)
- Matt Johnson (@mj1856)
- Brian Terlson (@bterlson)
This proposal is currently stage 2
Stage 3 Reviewers:
- Richard Gibson
- Bradley Farias
- Daniel Ehrenberg
Date has been a long time pain point in ECMAScript.
This proposes 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 breakdown of motivations see:
Fixing JavaScript Date
- All temporal APIs are non-mutating. All temporal objects are effectively immutable.
- All date values are based on the Proleptic Gregorian Calendar. Other calendar systems are out-of-scope for this proposal. However, we will consider how future APIs may interact with this one such that extending it to support other calendars may be possible in a future proposal.
- All time-of-day values are based on a standard 24-hour clock.
- Leap seconds are not represented.
The specification text is currently being updated to match the polyfill. Please rely on the polyfill linked from here for authoritative information until then.
A complete polyfill can be found here. It is being developed as specification in code.
An Temporal.Absolute represents a fixed point in time along the POSIX timeline. It does this by internally maintaining a slot for "Nanoseconds since the POSIX-Epoch".
See Temporal.Absolute Documentation for more detailed documentation.
A Temporal.TimeZone represents an IANA Timezone, a specific UTC-Offset or UTC itself. Because of this Temporal.TimeZone can be used to convert between Temporal.Absolute and Temporal.DateTime as well as finding out the offset at a specific Temporal.Absolute.
Temporal.TimeZone is also an iterable that give access to the IANA-Timezones supported by the system from the IANA time zone database (also listed here).
See Temporal.TimeZone Documentation for more detailed documentation.
A Temporal.DateTime represents a caldendar date and wall-clock time. That means it does not carry timezone information. However it can be converted to a Temporal.Absolute using a Temporal.TimeZone.
This can also be converted to object containing only partial information such as Temporal.Date and Temporal.Time.
See Temporal.DateTime Documentation for more detailed documentation.
A Temporal.Time object represents a wall-clock time. Since there is no date component this can not be directly translated to an absolute point in time. However it can be converted to a Temporal.Absolute by combining with a Temporal.Date using a Temporal.TimeZone.
See Temporal.Time Documentation for more detailed documentation.
A Temporal.Date object represents a calendar date. This means there is no way to convert this to an absolute point in time, however combining with a Temporal.Time a Temporal.DateTime can be obtained which in turn can be pinned to the absolute timeline.
This can also be converted to partial dates such as Temporal.YearMonth and Temporal.MonthDay.
See Temporal.Date Documentation for more detailed documentation.
A date without a day component. This is useful to express things like "the November 2010 meeting".
See Temporal.YearMonth Documentation for more 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 more detailed documentation.
A Temporal.Duration expresses a length of time. This is used fo date/time maths.
See Temporal.Duration Documentation for more detailed documentation.
Temporal.getAbsolute()- get the current system absolute timeTemporal.getTimeZone()- get the current system timezoneTemporal.getDateTime()- get the current system date/timeTemporal.getTime()- get the current system timeTemporal.getDate()- get the current system dateTemporal.getYearMonth()- get the current system year/monthTemporal.getMonthDay()- get the current system month/day
See Temporal Functions Documentation for more detailed documentation.