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.
newCivilDate(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.
letyear=civilDate.year;letmonth=civilDate.month;letday=civilDate.day;letcivilDate2=civilDate1.plus({months: 1});letcivilDateTime=civilDate.withTime(time);Represents a position on a 24-hour clock.
newCivilTime(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.
lethour=civilTime.hour;letminute=civilTime.minute;letsecond=civilTime.second;letmillisecond=civilTime.millisecond;letnanosecond=civilTime.nanosecond;letcivilTime2=civilTime1.plus({hours: 2,minutes: 4});letcivilDateTime=civilTime.withDate(date);Represents a whole day, and the position within that day.
newCivilDateTime(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.
letyear=civilDateTime.year;letmonth=civilDateTime.month;letday=civilDateTime.day;lethour=civilDateTime.hour;letminute=civilDateTime.minute;letsecond=civilDateTime.second;letmillisecond=civilDateTime.millisecond;letnanosecond=civilDateTime.nanosecond;letcivilDateTime=CivilDateTime.from(date,time);letcivilDateTime2=civilDateTime1.plus({days: 3,hours: 4,minutes: 2,seconds: 12});letcivilDate=civilDateTime.toCivilDate();letcivilTime=civilDateTime.toCivilTime();letzonedInstant=civilDateTime.withZone(timeZone[,options]);Represents an absolute point in time.
Counted as number of nanoseconds from 1970-01-01T00:00:00.000000000Z.
newInstant(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.
letmilliseconds=instant.milliseconds;letnanoseconds=instant.nanoseconds;letzonedInstant=instant.withZone(timeZone);Represents an absolute point in time, with an associated time zone.
newZonedInstant(instant,timeZone)letmilliseconds=zonedInstant.milliseconds;letnanoseconds=zonedInstant.nanoseconds;lettimeZone=zonedInstant.timeZone;letcivilDateTime=zonedInstant.toCivilDateTime();letcivilDate=zonedInstant.toCivilDate();letcivilTime=zonedInstant.toCivilTime();letinstant=zonedInstant.toInstant();Allows the user to create a new instance of any temporal object with new date-part values.
letmyCivilDate=newCivilDate(2016,2,29);letnewCivilDate=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.
letmyCivilDate=newCivilDate(2016,2,29);letnewCivilDate=myCivilDate.plus({years: 1,months: 2});//results in civil date with value 2017-4-28