Provides standard objects and functions for working with dates and times.
- Maggie Pint (@maggiepint)
- Matt Johnson (@mj1856)
- Brian Terlson (@bterlson)
This proposal is currently stage 1
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.
| 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 |
| Object name | Description | Example |
|---|---|---|
Instant |
A point on the universal timeline, typically represented in UTC. | 2017-12-31T00:00:00Z |
ZonedInstant |
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 ZonedInstant can be any of:
- Coordinated Universal Time, indicated by the string
'UTC' - The system local time zone, indicated by the string
'SYSTEM' - A fixed offset from UTC, indicated by a string in
'±HH:MM'or'±HHMM'format - A
ZoneorLinkname from the IANA time zone database, as also listed here.
Because a fixed offset is supported, there is no need for a separate OffsetDateTime type.
TBD
Represents a whole day, as a date on the proleptic Gregorian calendar.
new CivilDate(year, month, day)year: Integer value representing the year.month: Integer value representing the month, from1through12.day: Integer value representing the day, from1through the number of days for the givenmonthandyear, which may be28,29,30, or31.
let year = civilDate.year;
let month = civilDate.month;
let day = civilDate.day;let civilDate2 = civilDate1.plus({months: 1});
let civilDateTime = civilDate.withTime(time);Represents a position on a 24-hour clock.
new CivilTime(hour, minute[[[, second], millisecond], nanosecond])hour: Integer value representing the hour of the day, from0through23.minute: Integer value representing the minute within the hour, from0through59.second: Optional. Integer value representing the second within the minute, from0through59.millisecond: Optional. Integer value representing the millisecond within the second, from0through999.nanosecond: Optional. Integer value representing the nanosecond within the millisecond, from0through999999.
let hour = civilTime.hour;
let minute = civilTime.minute;
let second = civilTime.second;
let millisecond = civilTime.millisecond;
let nanosecond = civilTime.nanosecond;let civilTime2 = civilTime1.plus({hours: 2, minutes: 4});
let civilDateTime = civilTime.withDate(date);Represents a whole day, and the position within that day.
new CivilDateTime(year, month, day, hour, minute[, second[, millisecond[, nanosecond]]])year: Integer value representing the year.month: Integer value representing the month, from1through12.day: Integer value representing the day, from1through the number of days for the givenmonthandyear, which may be28,29,30, or31.hour: Integer value representing the hour of the day, from0through23.minute: Integer value representing the minute within the hour, from0through59.second: Optional. Integer value representing the second within the minute, from0through59.millisecond: Optional. Integer value representing the millisecond within the second, from0through999.nanosecond: Optional. Integer value representing the nanosecond within the millisecond, from0through999999.
let year = civilDateTime.year;
let month = civilDateTime.month;
let day = civilDateTime.day;
let hour = civilDateTime.hour;
let minute = civilDateTime.minute;
let second = civilDateTime.second;
let millisecond = civilDateTime.millisecond;
let nanosecond = civilDateTime.nanosecond;let civilDateTime = CivilDateTime.from(date, time);
let civilDateTime2 = civilDateTime1.plus({days: 3, hours: 4, minutes: 2, seconds: 12});
let civilDate = civilDateTime.toCivilDate();
let civilTime = civilDateTime.toCivilTime();
let zonedInstant = civilDateTime.withZone(timeZone[, options]);Represents an absolute point in time.
Counted as number of nanoseconds from 1970-01-01T00:00:00.000000000Z.
new Instant(milliseconds[, nanoseconds])milliseconds: Integer value representing the number of milliseconds elapsed from 1970-01-01 00:00:00.000 UTC, without regarding leap seconds.nanoseconds: Optional. Integer value representing the nanosecond within the millisecond.
let milliseconds = instant.milliseconds;
let nanoseconds = instant.nanoseconds;let zonedInstant = instant.withZone(timeZone);Represents an absolute point in time, with an associated time zone.
new ZonedInstant(instant, timeZone)let milliseconds = zonedInstant.milliseconds;
let nanoseconds = zonedInstant.nanoseconds;
let timeZone = zonedInstant.timeZone;let civilDateTime = zonedInstant.toCivilDateTime();
let civilDate = zonedInstant.toCivilDate();
let civilTime = zonedInstant.toCivilTime();
let instant = zonedInstant.toInstant();Allows the user to create a new instance of any temporal object with new date-part values.
let myCivilDate = new CivilDate(2016, 2, 29);
let newCivilDate = myDate.with({year: 2017, month: 3});
//results in civil date with value 2017-03-29Returns a new temporal object with the specified date parts added. Units will be added in order of size, descending.
let myCivilDate = new CivilDate(2016, 2, 29);
let newCivilDate = myCivilDate.plus({years: 1, months: 2});
//results in civil date with value 2017-4-28