Provides standard objects and functions for working with dates and times.
- Maggie Pint (@maggiepint)
- Philipp Dunkel (@pipobscure)
- Matt Johnson (@mj1856)
- Brian Terlson (@bterlson)
This proposal is currently stage 2
Proposed Spec Text is viewable here.
(Note, this is a work in progress.)
Stage 3 Reviewers:
- Richard Gibson
- Bradley Farias
- Daniel Ehrenberg
Date has been a long time pain point in ECMAScript.
This proposes temporal, a built in module 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 out of date. It will be updated as the proposal get closer to a stable state. Please rely on the markdown files linked from here for authoritative information until then.
A complete polyfill can be found here. It will be developed to remain in sync with this proposal.
Please see the Object Description for details on the shape and functionality of temporal objects as well as the Mental Model which underlies that API and explain the relationship between these objects.
There are also some Example Use-Cases to describe how these objects can be used in practice.
Also there were many long discussions on the naming of the Civil* objects. There is a short piece describing the pros and cons and arguments on how we reached the decision to name them Civil.
The word 'Civil' indicates an object that does not have a relationship to the global timeline (UTC). The object could be anywhere/in any place.
The word 'Instant' indicates an object that has a relationship to the global timeline (UTC), and can assertively be mapped to a UTC date.
| Object name | Description | Example |
|---|---|---|
CivilDate |
A date without any time or time zone reference. | 2017-12-31 |
CivilTime |
A time-of-day without any date or time zone reference. | 17:00:00 |
CivilDateTime |
A date and a time without any time zone reference. | 2017-12-31T12:00:00 |
CivilYearMonth |
A date without a day component | 2017-12 |
CivilMonthDay |
A date without a year component | 12-25 |
| Object name | Description | Example |
|---|---|---|
Instant |
A point on the universal timeline. | 2017-12-31T00:00:00Z |
OffsetDateTime |
A point on the universal timeline, with an associated offset. | 2017‑12‑31T09:00:00+09:00 |
ZonedDateTime |
A point on the universal timeline, with an associated time zone. | 2017‑12‑31T09:00:00+09:00[Asia/Tokyo] |
Note that the time zone of a ZonedDateTime needs to be a valid Zone or Link name from the
IANA time zone database, as also listed here.